 |
|
| If you can't view the Datasheet, Please click here to try to view without PDF Reader . |
|
|
|
| If you can't view the Datasheet, Please click here to try to view without PDF Reader . |
|
|
| Datasheet File OCR Text: |
| SPECTRA-2488 (PM5315) Driver Manual PM5315 SPECTRA-2488TM DRIVER MANUAL PROPRIETARY AND CONFIDENTIAL RELEASED ISSUE 2: NOVEMBER, 01 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 SPECTRA-2488 (PM5315) Driver Manual ABOUT THIS MANUAL AND SPECTRA-2488 This manual describes the Spectra-2488 device driver. It describes the driver's functions, data structures, and architecture. This manual focuses on the driver's interfaces to your application, real-time operating system, and to the device. It also describes in general terms how to modify and port the driver to your software and hardware platform. Audience This manual was written for people who need to: * * * Evaluate and test the Spectra-2488 devices Modify and add to the Spectra-2488 driver's functions Port the Spectra-2488 driver to a particular platform. References For more information about the Spectra-2488 driver, see the driver's release Notes. For more information about the Spectra-2488 device, see the documents listed in Table 1 and any related errata documents. Table 1: Related Documents Document Name Spectra-2488 Telecom Standard Product Data Sheet Document Number PMC-1990821 Note: Ensure that you use the document that PMC-Sierra issued for your version of the device and driver. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 2 SPECTRA-2488 (PM5315) Driver Manual Revision History Issue No. Issue 1 Issue 2 Issue Date November 2000 November 2001 Details of Change Document created Updated for driver production release: 1) Added side effect to spe2488GetStatus and spe2488GetCnt APIs: added latency of the APIs when used in QUAD mode with unused ports. 2) Added extra APIs to retrieve all stats for a given port. 3) Added to the function descriptions of Section, line, path and path-TU3 Termination APIs, to clarify the feature covered by those APIs. 4) Removed API spe2488DiagSysSideSysLoop Legal Issues None of the information contained in this document constitutes an express or implied warranty by PMC-Sierra, Inc. as to the sufficiency, fitness or suitability for a particular purpose of any such information or the fitness, or suitability for a particular purpose, merchantability, performance, compatibility with other parts or systems, of any of the products of PMC-Sierra, Inc., or any portion thereof, referred to in this document. PMC-Sierra, Inc. expressly disclaims all representations and warranties of any kind regarding the contents or use of the information, including, but not limited to, express and implied warranties of accuracy, completeness, merchantability, fitness for a particular use, or non-infringement. In no event will PMC-Sierra, Inc. be liable for any direct, indirect, special, incidental or consequential damages, including, but not limited to, lost profits, lost business or lost data resulting from any use of or reliance upon the information, whether or not PMC-Sierra, Inc. has been advised of the possibility of such damage. The information is proprietary and confidential to PMC-Sierra, Inc., and for its customers' internal use. In any event, no part of this document may be reproduced in any form without the express written consent of PMC-Sierra, Inc. (c) 2001 PMC-Sierra, Inc. All rights reserved PMC-2001285 (R2), ref PMC-2000048 (R4) Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 3 SPECTRA-2488 (PM5315) Driver Manual Trademarks SPECTRA-2488 is a trademark of PMC-Sierra, Inc. Contacting PMC-Sierra PMC-Sierra, Inc. 8555 Baxter Place Burnaby, BC Canada V5A 4V7 Tel: +1-604- 415-6000 Fax: +1-604-415-6200 Document Information: document@pmc-sierra.com Corporate Information: info@pmc-sierra.com Technical Support: apps@pmc-sierra.com Web Site: http://www.pmc-sierra.com Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 4 SPECTRA-2488 (PM5315) Driver Manual TABLE OF CONTENTS About this Manual and Spectra-2488.................................................................................. 2 Audience ................................................................................................................... 2 References ................................................................................................................ 2 Revision History ........................................................................................................ 3 Legal Issues .............................................................................................................. 3 Contacting PMC-Sierra ............................................................................................. 4 Table of Contents ................................................................................................................ 5 List of Figures.................................................................................................................... 12 List of Tables ..................................................................................................................... 13 1 2 Introduction ................................................................................................................. 15 Driver Functions and Features ................................................................................... 16 2.1 General Driver Functions............................................................................................ 16 Open/Close Driver Module ...................................................................................... 16 Start/Stop Driver Module ......................................................................................... 16 Add/Delete Device................................................................................................... 16 Device Initialization.................................................................................................. 16 Activate/De-Activate Device .................................................................................... 17 Read/Write Device Registers .................................................................................. 17 Interrupt Servicing/Polling ....................................................................................... 17 Statistics Collection ................................................................................................. 17 2.2 SPECTRA-2488 Specific Driver Functions................................................................. 18 Input/Output............................................................................................................. 18 Section Overhead.................................................................................................... 18 Line Overhead......................................................................................................... 18 Path Overhead ........................................................................................................ 19 Device Update......................................................................................................... 19 Device Diagnostics.................................................................................................. 19 Statistics and Alarm Monitoring ............................................................................... 19 Specific Callback Functions .................................................................................... 20 3 Software Architecture ................................................................................................. 21 3.1 Driver External Interfaces ........................................................................................... 21 Application Programming Interface ......................................................................... 22 Real-Time Operating System (RTOS) Interface...................................................... 22 Hardware Interface.................................................................................................. 22 3.2 Main Components....................................................................................................... 22 Module Data-Block and Device(s) Data-Blocks ...................................................... 24 Interrupt-Service Routine ........................................................................................ 24 Deferred-Processing Routine .................................................................................. 24 Alarms, Status and Statistics ................................................................................... 25 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 5 SPECTRA-2488 (PM5315) Driver Manual Input/Output............................................................................................................. 25 Section Overhead.................................................................................................... 25 Line Overhead......................................................................................................... 25 Path Overhead ........................................................................................................ 25 Device Diagnostics.................................................................................................. 25 3.3 Software States........................................................................................................... 26 Module States.......................................................................................................... 27 Device States .......................................................................................................... 27 3.4 Processing Flows ....................................................................................................... 28 Module Management............................................................................................... 29 Device Management ............................................................................................... 30 3.5 Interrupt Servicing ...................................................................................................... 31 Calling spe2488ISR................................................................................................. 31 Calling spe2488DPR ............................................................................................... 32 Calling spe2488Poll................................................................................................. 33 3.6 Initialization of the Device for Various Payload Mappings.......................................... 33 4 Data Structures ........................................................................................................... 37 4.1 Constants.................................................................................................................... 37 4.2 Structures Passed by the Application ......................................................................... 38 Module Initialization Vector: MIV ............................................................................. 38 Device Initialization Vector: DIV .............................................................................. 38 ISR Enable/Disable Mask........................................................................................ 44 Statistics Counters (CNT)........................................................................................ 48 Alarm Status (STATUS) ........................................................................................... 51 Time-Slot Structure: TSLOT .................................................................................... 55 4.3 Structures in the Driver's Allocated Memory............................................................... 55 Module Data Block: MDB ........................................................................................ 55 Device Data Block: DDB ......................................................................................... 56 4.4 Structures Passed through RTOS Buffers.................................................................. 59 Interrupt-Service Vector: ISV................................................................................... 59 Deferred-Processing Vector: DPV........................................................................... 60 4.5 Global Variables.......................................................................................................... 60 5 Application Programming Interface ............................................................................ 61 5.1 Module Management.................................................................................................. 61 Opening the Driver Module: spe2488ModuleOpen................................................. 61 Closing the Driver Module: spe2488ModuleClose .................................................. 62 Starting the Driver Module: spe2488ModuleStart.................................................... 62 Stopping the Driver Module: spe2488ModuleStop.................................................. 63 5.2 Profile Management ................................................................................................... 63 Setting an Initialization Profile: spe2488SetInitProfile............................................. 64 Getting an Initialization Profile: spe2488GetInitProfile............................................ 64 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 6 SPECTRA-2488 (PM5315) Driver Manual Clearing an Initialization Profile: spe2488ClrInitProfile ........................................... 65 5.3 Device Management................................................................................................... 65 Adding a Device: spe2488Add ................................................................................ 65 Deleting a Device: spe2488Delete.......................................................................... 66 Initializing a Device: spe2488Init............................................................................. 66 Updating the Configuration of a Device: spe2488Update....................................... 67 Resetting a Device: spe2488Reset......................................................................... 67 Activating a Device: spe2488Activate ..................................................................... 68 De-Activating a Device: spe2488DeActivate........................................................... 68 5.4 Device Read and Write............................................................................................... 69 Reading from Device Registers: spe2488Read ...................................................... 69 Writing to Device Registers: spe2488Write............................................................. 69 Reading from a block of Device Registers: spe2488ReadBlock............................. 70 Writing to a Block of Device Registers: spe2488WriteBlock ................................... 71 5.5 Input/Output ................................................................................................................ 72 Setting Timeslot Mapping Mode: spe2488IOSetMapMode..................................... 72 Getting Timeslot Mapping Mode: spe2488IOGetMapMode.................................... 72 Creating a Timeslot Mapping: spe2488IOMapSlot ................................................. 73 Determining if a Timeslot is being Multicasted: spe2488IOIsMulticast ................... 74 Getting Destination Timeslot(s): spe2488IOGetDestSlot........................................ 74 Getting Source Timeslot: spe2488IOGetSrcSlot..................................................... 75 Getting Active Configuration Page: spe2488IOGetPage ........................................ 76 Setting Active Configuration Page: spe2488IOSetPage ......................................... 76 Inserting IDLE Data Pattern: spe2488IOInsertIdle.................................................. 77 5.6 Section Overhead ....................................................................................................... 77 Selecting the Section Termination Mode: spe2488SOHTermination ...................... 77 Reading and Setting the Section Trace Message (J0): spe2488SectionTraceMsg ................................................................................ 78 Writing the J0 Byte: spe2488SOHWriteJ0 .............................................................. 79 Writing the Z0 Byte: spe2488SOHWriteZ0 ............................................................. 79 Writing the D1-D3 Byte: spe2488SOHWriteD1D3 .................................................. 80 Writing the E1 Byte: spe2488SOHWriteE1 ............................................................. 80 Writing the F1 Byte: spe2488SOHWriteF1 ............................................................. 81 Forcing Out-of-Frame: spe2488SOHForceOOF ..................................................... 81 Forcing Errors in the Framing Bytes: spe2488SOHDiagFB.................................... 82 Forcing Section BIP-8 Errors: spe2488SOHDiagB1............................................... 82 Forcing Loss-of-Signal: spe2488SOHDiagLOS ...................................................... 83 5.7 Line Overhead ............................................................................................................ 83 Selecting the Line Termination Mode: spe2488LOHTermination ............................ 83 Configuring Signal Fail (SF) and Signal Degrade (SD): spe2488LOHCfgSFSD ..................................................................................... 84 Reading the Received K1 and K2 Bytes: spe2488LOHReadK1K2 ........................ 85 Writing the Transmitted K1 and K2 Bytes: spe2488LOHWriteK1K2....................... 86 Writing the D4-D12 Byte: spe2488LOHWriteD4D12............................................... 87 Reading the S1 Byte: spe2488LOHReadS1 ........................................................... 87 Writing the S1 Byte: spe2488LOHWriteS1 ............................................................. 88 Writing the Z1 Byte: spe2488LOHWriteZ1.............................................................. 88 Writing the Z2 Byte: spe2488LOHWriteZ2.............................................................. 89 Writing the E2 Byte: spe2488LOHWriteE2 ............................................................. 89 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 7 SPECTRA-2488 (PM5315) Driver Manual Inserting Line AIS: spe2488LOHInsertLineAIS ....................................................... 90 Inserting Line Remote Defect Indication: spe2488LOHInsertLineRDI.................... 90 Forcing Line BIP-8 Errors: spe2488LOHDiagB2 .................................................... 91 Forcing Errors in the Payload Pointer: spe2488LOHDiagH1H2 ............................. 92 5.8 Path Overhead ........................................................................................................... 92 Selecting the Path Termination Mode: spe2488POHTermination ........................... 93 Selecting the TU3 Path Termination Mode: spe2488POHTerminationTU3 ............ 94 Retrieving and Setting the Path Trace Messages: spe2488PathTraceMsg............ 94 Retrieving and Setting the TU3 Path Trace Messages: spe2488PathTraceMsgTU3 .............................................................................. 95 Receive Path Overhead (RPOH) ............................................................................ 96 Retrieving and Setting the Received Path Signal Label: spe2488RPOHPathSignalLabel ....................................................................... 96 Retrieving and Setting the TU3 Path Signal Label: spe2488PathSignalLabelTU3 ........................................................................... 97 Forcing Loss-of-Pointer: spe2488RPOHDiagLOP .................................................. 97 Forcing Pointer Justification: spe2488RPOHDiagPJ .............................................. 98 Retrieving the Received Pointer Value: spe2488RPOHReadPtr ............................ 98 Retrieving the Received TU3 Pointer Value: spe2488RPOHReadPtrTU3 ............. 99 Transmit Path Overhead (TPOH).......................................................................... 100 Retrieving and Setting the Transmit Path Signal Label: spe2488TPOHPathSignalLabel...................................................................... 100 Forcing Path AIS: spe2488TPOHInsertPAIS ........................................................ 100 Forcing Path BIP-8 Errors: spe2488TPOHDiagB3 ............................................... 101 Forcing TU3 Path BIP-8 Errors: spe2488TPOHDiagB3TU3................................. 101 Writing the Path Remote Error Indication Count: spe2488TPOHInsertPREI ....... 102 Writing the TU3 Path Remote Error Indication Count: spe2488TPOHInsertPREITU3........................................................................ 103 Controlling Pointer Justification: spe2488TPOHDiagPJ ....................................... 103 Writing the J1 Byte: spe2488TPOHWriteJ1 .......................................................... 104 Writing the J1-TU3 Byte: spe2488TPOHWriteJ1TU3 ........................................... 104 Writing the C2 Byte: spe2488TPOHWriteC2 ........................................................ 105 Writing the C2-TU3 Byte: spe2488TPOHWriteC2TU3.......................................... 105 Writing the F2 Byte: spe2488TPOHWriteF2 ......................................................... 106 Writing the F2-TU3 Byte: spe2488TPOHWriteF2TU3 .......................................... 107 Writing the Z3 Byte: spe2488TPOHWriteZ3 ......................................................... 107 Writing the Z3-TU3 Byte: spe2488TPOHWriteZ3TU3 .......................................... 108 Writing the Z4 Byte: spe2488TPOHWriteZ4 ......................................................... 108 Writing the Z4-TU3 Byte: spe2488TPOHWriteZ4TU3 .......................................... 109 Writing the Z5 Byte: spe2488TPOHWriteZ5 ......................................................... 109 Writing the Z5-TU3 Byte: spe2488TPOHWriteZ5TU3 .......................................... 110 Retrieving Current Transmit Pointer Value: spe2488TPOHReadPtr..................... 110 Forcing AU Pointer Value: spe2488TPOHForceTxPtr ...........................................111 5.9 DROP/ADD Bus PRBS Generator and Monitor (DPGM / APGM) ........................... 112 DROP Bus PRBS Generator and Monitor (DPGM) .............................................. 112 Configuring the PRBS Generator: spe2488DPGMGenCfg................................... 112 Configuring the PRBS Monitor: spe2488DPGMMonCfg....................................... 113 Forcing Bit Errors: spe2488DPGMGenForceErr................................................... 113 Forcing a Resynchronization: spe2488DPGMMonResync................................... 114 ADD Bus PRBS Generator and Monitor (APGM) ................................................. 114 Configuring the PRBS Generator: spe2488APGMGenCfg................................... 114 Configuring the PRBS Monitor: spe2488APGMMonCfg....................................... 115 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 8 SPECTRA-2488 (PM5315) Driver Manual Forcing Bit Errors: spe2488APGMGenForceErr ................................................... 116 Forcing a Resynchronization: spe2488APGMMonResync ................................... 116 5.10 Interrupt Service Functions ................................................................................... 117 Configuring ISR Processing: spe2488ISRConfig.................................................. 117 Getting the Interrupt Status Mask: spe2488GetMask ........................................... 117 Setting the Interrupt Enable Mask: spe2488SetMask........................................... 118 Clearing the Interrupt Enable Mask: spe2488ClearMask ..................................... 118 Polling the Interrupt Status Registers: spe2488Poll .............................................. 119 Interrupt-Service Routine: spe2488ISR ................................................................ 119 Deferred-Processing Routine: spe2488DPR ........................................................ 120 Setting the Thresholds for Callbacks: spe2488SetThresh.................................... 120 Getting the Thresholds for Callbacks: spe2488GetThresh ................................... 121 Getting the Event Counters: spe2488GetThreshCntr ........................................... 121 5.11 Alarm, Status and Statistics Functions .................................................................. 122 Configuring the Device Statistics: spe2488CfgStats ............................................. 122 Statistics Collection Routine: spe2488GetCnt....................................................... 122 Statistics Collection Routine: spe2488GetCntStm4 .............................................. 123 Getting Counter for SOH and LOH Block: spe2488GetCntSOHLOH................... 123 Getting Counter for RPOH Block: spe2488GetCntRPOH..................................... 124 Getting Counter for TPOH Block: spe2488GetCntTPOH ..................................... 124 Getting Current Alarm Status: spe2488GetStatus................................................. 125 Getting Current Alarm Status: spe2488GetStatusStm4 ........................................ 126 Getting Current Alarm Status for IO block: spe2488GetStatusIO ......................... 126 Getting Current Alarm Status for SOH and LOH block: spe2488GetStatusSOHLOH ........................................................................... 127 Getting Current Alarm Status for RPOH block: spe2488GetStatusRPOH ........... 127 Getting Current Alarm Status for TPOH block: spe2488GetStatusTPOH ............ 128 5.12 Device Diagnostics................................................................................................ 128 Testing Register Accesses: spe2488DiagTestReg................................................ 128 Enabling Line-Side Line Loopbacks: spe2488DiagLineSideLineLoop ................. 129 Enabling Line-Side System Loopbacks: spe2488DiagLineSideSysLoop ............. 129 Enabling System-Side Line Loopbacks: spe2488DiagSysSideLineLoop ............. 130 5.13 Callback Functions ................................................................................................ 130 Notifying the Application of IO Events: cbackSpe2488IO ..................................... 131 Notifying the Application of SOH Events: cbackSpe2488SOH ............................. 131 Notifying the Application of LOH Events: cbackSpe2488LOH .............................. 132 Notifying the Application of RPOH Events: cbackSpe2488RPOH ........................ 132 Notifying the Application of RPOH-TU3 Events: cbackSpe2488RPOHTU3 ......... 133 Notifying the Application of TPOH Events: cbackSpe2488TPOH ......................... 133 Notifying the Application of DPGM Events: cbackSpe2488DPGM ....................... 134 Notifying the Application of APGM Events: cbackSpe2488APGM ........................ 134 6 Hardware Interface ................................................................................................... 135 6.1 Device I/O ................................................................................................................. 135 Reading from a Device Register: sysSpe2488Read............................................. 135 Writing to a Device Register: sysSpe2488Write.................................................... 135 Polling a Bit: sysSpe2488PollBit ........................................................................... 136 6.2 System-Specific Interrupt Servicing.......................................................................... 136 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 9 SPECTRA-2488 (PM5315) Driver Manual Installing the ISR Handler: sysSpe2488ISRHandlerInstall.................................... 137 ISR Handler: sysSpe2488ISRHandler .................................................................. 137 DPR Task: sysSpe2488DPRTask.......................................................................... 138 Removing the ISR Handler: sysSpe2488ISRHandlerRemove.............................. 138 7 RTOS Interface......................................................................................................... 139 7.1 Memory Allocation/De-Allocation.............................................................................. 139 Allocating Memory: sysSpe2488MemAlloc ........................................................... 139 Freeing Memory: sysSpe2488MemFree ............................................................... 139 Initializing Memory: sysSpe2488MemSet ............................................................. 140 Copying Memory: sysSpe2488MemCpy ............................................................... 140 7.2 Buffer Management .................................................................................................. 141 Starting Buffer Management: sysSpe2488BufferStart........................................... 141 Getting an ISV Buffer: sysSpe2488ISVBufferGet ................................................. 141 Returning an ISV Buffer: sysSpe2488ISVBufferRtn.............................................. 142 Getting a DPV Buffer: sysSpe2488DPVBufferGet ................................................ 142 Returning a DPV Buffer: sysSpe2488DPVBufferRtn ............................................ 142 Stopping Buffer Management: sysSpe2488BufferStop ......................................... 143 7.3 Timers ....................................................................................................................... 143 Sleeping a Task: sysSpe2488TimerSleep ............................................................. 143 7.4 Preemption ............................................................................................................... 144 Disabling Preemption: sysSpe2488PreemptDisable............................................. 144 Re-Enabling Preemption: sysSpe2488PreemptEnable ........................................ 144 8 Porting the SPECTRA-2488 Driver .......................................................................... 145 8.1 Driver Source Files ................................................................................................... 145 8.2 Driver Porting Procedures ........................................................................................ 146 Step 1: Porting the RTOS Extensions ................................................................... 146 Step 2: Porting the Driver to Your Hardware Platform........................................... 148 Step 3: Porting the Application-Specific Elements ................................................ 149 Step 4: Building the Driver..................................................................................... 150 Appendix A: Driver Return Codes ................................................................................... 151 Appendix B: SPECTRA-2488 Events ............................................................................. 152 Appendix C: Coding Conventions ................................................................................... 155 Variable Type Definitions ....................................................................................... 155 Naming Conventions ............................................................................................. 155 Macros................................................................................................................... 156 Constants .............................................................................................................. 156 Structures .............................................................................................................. 156 Functions ............................................................................................................... 157 Variables................................................................................................................ 157 File Organization ................................................................................................... 158 API Files ................................................................................................................ 158 Hardware Dependent Files.................................................................................... 158 RTOS Dependent Files ......................................................................................... 159 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 10 SPECTRA-2488 (PM5315) Driver Manual Other Driver Files .................................................................................................. 159 List of Terms .................................................................................................................... 160 Acronyms ........................................................................................................................ 161 Index................................................................................................................................ 162 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 11 SPECTRA-2488 (PM5315) Driver Manual LIST OF FIGURES Figure 1: Driver External Interfaces ................................................................................. 21 Figure 2: Driver Architecture............................................................................................ 23 Figure 3: Driver Software States....................................................................................... 26 Figure 4: Module Management Flow Diagram................................................................. 29 Figure 5: Device Management Flow Diagram.................................................................. 30 Figure 6: Interrupt Service Model..................................................................................... 31 Figure 7: Polling Service Model ....................................................................................... 33 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 12 SPECTRA-2488 (PM5315) Driver Manual LIST OF TABLES Table 1: Related Documents ............................................................................................... 2 Table 2: Payload Mapping Parameters.............................................................................. 34 Table 3: 48xSTS-1 Configuration..................................................................................... 34 Table 4: STS-48c Configuration ....................................................................................... 35 Table 5: STS-12c / STS-24c / STS-12c Configuration ..................................................... 35 Table 6: 4xSTS-3c/STS-12c/4xTUG-3/12xSTS-1 Configuration .................................... 36 Table 7: SPECTRA-2488 Module Initialization Vector: sSPE2488_MIV ....................... 38 Table 8: SPECTRA-2488 Device Initialization Vector: sSPE2488_DIV ......................... 39 Table 9: PRBS Generator and Monitor Configuration: sSPE2488_CFG_PRBS.............. 40 Table 10: Counters Config: sSPE2488_CFG_SFSD ........................................................ 41 Table 11: SPECTRA-2488 Statistic Counters: sSPE2488_CFG_CNT............................. 42 Table 12: SPECTRA-2488 ISR Mask: sSPE2488_MASK............................................... 44 Table 13: SPECTRA-2488 Statistics Counters: sSPE2488_STAT_CNT ......................... 48 Table 14: SPECTRA-2488 Section Overhead Statistics Counters: sSPE2488_STAT_CNT_SOH................................................................................... 48 Table 15: SPECTRA-2488 Line Overhead Status: sSPE2488_STAT_CNT_LOH .......... 49 Table 16: SPECTRA-2488 Receive Path Processing Statistics Counters: sSPE2488_STAT_CNT_RPOH ................................................................................ 49 Table 17: SPECTRA-2488 Receive Path Processing Statistics Counters: sSPE2488_STAT_CNT_TPOH ................................................................................ 50 Table 18: SPECTRA-2488 Alarm Status: sSPE2488_STATUS ....................................... 51 Table 19: SPECTRA-2488 Input / Output Alarm Status: sSPE2488_STATUS_IO ......... 51 Table 20: SPECTRA-2488 Section Overhead Alarm Status: sSPE2488_STATUS_SOH........................................................................................ 52 Table 21: SPECTRA-2488 Line Overhead Alarm Status: sSPE2488_STATUS_LOH ....................................................................................... 52 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 13 SPECTRA-2488 (PM5315) Driver Manual Table 22: SPECTRA-2488 Receive Path Overhead Alarm Status: sSPE2488_STATUS_RPOH ..................................................................................... 52 Table 23: SPECTRA-2488 Transmit Path Overhead Alarm Status: sSPE2488_STATUS_TPOH ..................................................................................... 54 Table 24: SPECTRA-2488 Time-Slot: sSPE2488_TSLOT.............................................. 55 Table 25: SPECTRA-2488 Module Data Block: sSPE2488_MDB.................................. 56 Table 26: SPECTRA-2488 Device Data Block: sSPE2488_DDB ................................... 57 Table 27: SPECTRA-2488 Interrupt-Service Vector: sSPE2488_ISV ............................. 59 Table 28: SPECTRA-2488 Deferred-Processing Vector: sSPE2488_DPV ...................... 60 Table 29: Return Codes................................................................................................... 151 Table 30: SPECTRA-2488 Events for IO callbacks ....................................................... 152 Table 31: SPECTRA-2488 Events for SOH callbacks ................................................... 152 Table 32: SPECTRA-2488 Events for LOH callbacks ................................................... 152 Table 33: SPECTRA-2488 Events for RPOH, RPOH-TU3 and TPOH callbacks ......... 153 Table 34: SPECTRA-2488 Events for DPGM and APGM callbacks............................. 154 Table 35: Variable Type Definitions................................................................................ 155 Table 36: Naming Conventions....................................................................................... 155 Table 37: File Naming Conventions ............................................................................... 158 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 14 SPECTRA-2488 (PM5315) Driver Manual Introduction 1 INTRODUCTION The following sections of the SPECTRA-2488 Driver Manual describe the SPECTRA-2488 device driver. The code provided throughout this document is written in C language. This has been done to promote greater driver portability to other embedded hardware (Section 6) and RealTime Operating System environments (Section 7). Section 3 of this document, Software Architecture, defines the software architecture of the SPECTRA-2488 device driver by including a discussion of the driver's external interfaces and its main components. The Data Structure information in Section 3.6 describes the elements of the driver that configure or control its behavior. Included here are the constants, variables and structures that the SPECTRA-2488 device driver uses to store initialization, configuration and status information. Section 5 provides a detailed description of each function that is a member of the SPECTRA-2488 driver Application Programming Interface (API). The section outlines function calls that hide device-specific details and application callbacks that notify the user of significant device events. For your convenience, section 8 of this manual provides a brief guide for porting the SPECTRA2488 device driver to your hardware and RTOS platform. In addition, an extensive Appendix (page 151) and Index (page 162) provides you with useful reference information. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 15 SPECTRA-2488 (PM5315) Driver Manual Driver Functions and Features 2 DRIVER FUNCTIONS AND FEATURES This section describes the main functions and features supported by the SPECTRA-2488 driver. 2.1 General Driver Functions Open/Close Driver Module Opening the driver module allocates all the memory needed by the driver and initializes all module level data structures. Closing the driver module shuts down the driver module gracefully after deleting all devices that are currently registered with the driver, and releases all the memory allocated by the driver. Start/Stop Driver Module Starting the driver module involves allocating all RTOS resources needed by the driver such as timers and semaphores (except for memory, which is allocated during the Open call). Stopping the driver module involves de-allocating all RTOS resources allocated by the driver without changing the amount of memory allocated to it. Add/Delete Device Adding a device involves verifying that the device exists, associating a device Handle to the device, and storing context information about it. The driver uses this context information to control and monitor the device. Deleting a device involves shutting down the device and clearing the memory used for storing context information about this device. Device Initialization The initialization function resets then initializes the device and any associated context information about it. The driver uses this context information to control and monitor the SPECTRA-2488 device. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 16 SPECTRA-2488 (PM5315) Driver Manual Driver Functions and Features Activate/De-Activate Device Activating a device puts it into its normal mode of operation by enabling interrupts and other global registers. A successful device activation also enables other API invocations. On the contrary, de-activating a device removes it from its operating state, and disables interrupts and other global registers. Read/Write Device Registers These functions provide a `raw' interface to the device. Device registers that are both directly and indirectly accessible are available for both inspection and modification via these functions. If applicable, block reads and writes are also available. Interrupt Servicing/Polling Interrupt Servicing is an optional feature. The user can disable device interrupts and instead poll the device periodically to monitor status and check for alarm/error conditions. Both polling and interrupt driven approaches detect a change in device status and report the status to a Deferred-Processing Routine (DPR). The DPR then invokes application callback functions based on the status information retrieved. This allows the driver to report significant events that occur within the device to the application. Statistics Collection Functions are provided to retrieve a snapshot of the various counts that are accumulated by the SPECTRA-2488 device. Routines should be invoked often enough to avoid letting the counters to saturate. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 17 SPECTRA-2488 (PM5315) Driver Manual Driver Functions and Features 2.2 SPECTRA-2488 Specific Driver Functions These functions provide control and monitoring of the various sections of the SPECTRA-2488 device. These sections are generally enabled or disabled and configured by the MODE specified during device initialization. Changes to these registers that would violate the characteristics of the initialized mode should be disallowed. Input/Output Functions are provided to configure the line side and system side interface of the SPECTRA2488. * * Configures the Time Slot Interchange (TSI) Enables / Disables insertion of IDLE characters. Section Overhead Functions are provided to control the Section Overhead processing. * * * * Enable/Disable Section Overhead termination Read / write the section trace message (J0). Read B1 error counter. Detects and reports TIM, TIU, SF, SD, LOS, OOF, LOF. Line Overhead Functions are provided to control the line overhead processing. * * * * * * * Enable/Disable line overhead termination Read / write the APS bytes (K1, K2) Read / write the synchronization byte (S1) Read the B2 error counter and REI counter Force Line AIS Configure to automatically insert line RDI, line REI or line AIS Detects and reports LRDI, LREI, LAIS and APS byte failure Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 18 SPECTRA-2488 (PM5315) Driver Manual Driver Functions and Features Path Overhead Functions are provided to control the path and path-TU3 overhead processing. * * * * * * Enable/Disable Path Overhead termination Read/write the path trace messages (J1). Read/write the path signal labels (C2). Read the B3 error counter and REI counter. Configure to automatically insert path RDI, path enhanced RDI, path REI and path AIS. Detect and report TIM, TIU, PSLM, PSLU, LOP, path RDI, path enhanced RDI, path REI, path AIS and PDI. Device Update A function is provided to update the device's configuration without forcing a hardware reset. Device Diagnostics * * * * * Device register read/write test Line-side line loopback from the line side receive stream to the transmit stream Line-side system loopback from the system side transmit stream to the receive stream System-side system loopback from the system side transmit stream to the system side receive stream (on a per STS-1/STM-0 basis). System-side line loopback from the ADD Telecombus to the DROP Telecombus (on a per STS-1/STM-0 basis). Statistics and Alarm Monitoring Functions to gather statistics and do alarm monitoring. * * * Retrieve a snapshot of the clock activity bits. Retrieve a snapshot of the current alarm status for the various Sonet/SDH alarms (LOP, OOF, LOF, LOS, xAIS, xRDI, xTIU, xTIM...). Read the current B1, B2, B3, B3-TU3, REI, REI-TU3 counts. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 19 SPECTRA-2488 (PM5315) Driver Manual Driver Functions and Features Specific Callback Functions Callback functions are available to the application for event notification from the device driver. Applications will be notified via the callback functions for selected events of interest such as: * * * * * * * Detection of an IO alarm condition (such as a clock error condition) Detection of a Section Overhead alarm condition Detection of a Line overhead alarm condition Detection of a Path Overhead alarm condition Detection of a Path-TU3 overhead alarm condition Detection of a Drop bus PRBS generator and monitor (DPGM) alarm condition Detection of an Add bus PRBS generator and monitor (APGM) alarm condition Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 20 SPECTRA-2488 (PM5315) Driver Manual Software Architecture 3 SOFTWARE ARCHITECTURE This section describes the software architecture of the SPECTRA-2488 device driver. This includes a discussion of the driver's external interfaces and its main components. 3.1 Driver External Interfaces Figure 1 illustrates the external interfaces defined for the SPECTRA-2488 device driver. Figure 1: Driver External Interfaces Application Function Calls Application Callbacks Service Callbacks SPECTRA-2488 Device Driver RTOS Service Calls Hardware Interrupts Register Accesses SPECTRA-2488 Devices Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 21 SPECTRA-2488 (PM5315) Driver Manual Software Architecture Application Programming Interface The driver Application Programming Interface (API) is a list of high-level functions that can be invoked by application programmers to configure, control, and monitor the SPECTRA-2488 devices. The API functions perform operations that are more meaningful from a system's perspective. The API includes functions such as: * * * * Initialize the device(s) Perform diagnostic tests Validate configuration information Retrieve status and statistics information The driver API functions use the services of the other driver components to provide this systemlevel functionality to the application programmer. The driver API also consists of callback routines that are used to notify the application of significant events that take place within the device(s) and module. Real-Time Operating System (RTOS) Interface The driver's RTOS interface provides functions that let the driver use RTOS services. The driver requires the memory, interrupt, and preemption services from the RTOS. The RTOS interface functions perform the following tasks for the driver: * * * Allocate and de-allocate memory Manage buffers for the ISR and the DPR Enable and disable preemption The RTOS interface also includes service callbacks. These are functions installed by the driver using RTOS service calls such as installing interrupts. These service callbacks are invoked when an interrupt occurs. Note: You must modify the RTOS interface code to suit your RTOS. Hardware Interface The hardware interface provides functions that read from and write to the device registers. The hardware interface also provides a template for the ISR that the driver calls when the device raises a hardware interrupt. You must modify this function based on the interrupt configuration of your system. 3.2 Main Components Figure 2 illustrates the top-level architectural components of the SPECTRA-2488 device driver. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 22 SPECTRA-2488 (PM5315) Driver Manual Software Architecture The driver includes the following main components: * * * * * * * * * Module and device(s) data-blocks Interrupt-Service Routine Deferred-Processing Routine Alarm, status and statistics Input/Output Section Overhead Line overhead Path Overhead Device diagnostics Figure 2: Driver Architecture Application Function Calls Application Callbacks Driver API Service Callbacks RTOS Interface Service Calls RTOS Deferred Processing Routine Alarm, Status & Statistics Device Diagnostics Input / Output Interrupt Context Module Data Block Device Data Blocks Section Overhead Line Overhead Interrupt Service Routine ....... Path Overhead Hardware Interface Hardware Interrupts Register Accesses SPECTRA-2488 Devices Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 23 SPECTRA-2488 (PM5315) Driver Manual Software Architecture Module Data-Block and Device(s) Data-Blocks The Module Data-Block (MDB) is the top layer data structure; it is created by the SPECTRA2488 driver to store context information about the driver module, such as: * * * Module state Maximum number of devices The DDB(s) The Device Data-Block (DDB) is contained in the MDB and is initialized by the driver module for each SPECTRA-2488 device that is registered. There is one DDB per device and there is a limit on the number of DDBs; that limit is set by the user when the module is initialized. The DDB is used to store context information about one device, such as: * * * * Device state Control information Initialization parameters Callback function pointers Interrupt-Service Routine The SPECTRA-2488 driver provides an ISR called spe2488ISR that checks if there is any valid interrupt condition present for the device. This function can be used by a system-specific interrupt-handler function to service interrupts raised by the device. The low-level interrupt-handler function that traps the hardware interrupt and calls spe2488ISR is system and RTOS dependent. Therefore, it is outside the scope of the driver. Example implementations of an interrupt handler and functions that install and remove it are provided as a reference in section 6.2. You can customize these example implementations to suit your specific needs. See section 3.5 for a detailed explanation of the ISR and interrupt-servicing model. Deferred-Processing Routine The SPECTRA-2488 driver provides a DPR called spe2488DPR that processes any interrupt condition gathered by the ISR for that device. Typically, a system specific function, which runs as a separate task within the RTOS, will call spe2488DPR. Example implementations of a DPR task and functions that install and remove it are provided as a reference in section 6.2. You can customize these example implementations to suit your specific needs. See section 3.5 for a detailed explanation of the DPR and the interrupt-servicing model. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 24 SPECTRA-2488 (PM5315) Driver Manual Software Architecture Alarms, Status and Statistics The alarm, status and statistics section is responsible for monitoring alarms, tracking a device's status information, and retrieving statistical counts for each device registered with (added to) the driver. Input/Output The input / output block is responsible for configuring the line side and system side device interfaces. On the line-side, functions are provided to control the 2488 Mbps clock/data interface and the ring control port. On the system-side, functions are provided to control the Add/Drop Telecom Bus data interfaces and the Time-Slot Interchange (TSI). Section Overhead The Section Overhead block provides functions to control and monitor the Section Overhead processing. Read / Write access is given to the section trace message (J0). This message is compared with a configurable reference and mismatches are reported. Access is provided to the Section BIP-8 (B1) errors counter. Section Overhead alarms are detected and reported. For diagnostic purposes, errors can be introduced in the Section Overhead bytes. Line Overhead The Line Overhead block is responsible for configuring and monitoring the line overhead on both the receive and transmit sides. Read / Write access is given to the APS bytes (K1 and K2) and most of the other overhead bytes. Access is provided to the Line BIP-8 (B2) errors and REI. Line overhead alarms are detected and reported. For diagnostic purposes, errors can be introduced in the line overhead bytes. Additional functions are provided to configure the device to automatically insert line RDI, line REI and line AIS. Path Overhead The Path Overhead block configures and monitors the Path Overhead (and Path Overhead TU3 if available) on both the receive and the transmit sides. Read / Write access is given to the path trace message (J1) and the path signal label (C2). Both are compared with a configurable reference and mismatches are reported. Access is provided to the Path BIP-8 (B3) errors and REI counters. Path Overhead alarms are detected and reported. For diagnostic purposes, errors can be introduced in the Path Overhead bytes. Additional functions are provided to configure the device to automatically insert path RDI, path enhanced RDI, path REI and path AIS. Device Diagnostics The device diagnostics API can be used to isolate/identify problems within the device and its interfaces. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 25 SPECTRA-2488 (PM5315) Driver Manual Software Architecture 3.3 Software States Figure 3 shows the software state diagram for the SPECTRA-2488 driver. State transitions occur on the successful execution of the corresponding transition functions shown. State information helps maintain the integrity of the MDB and DDB(s) by controlling the set of operations allowed in each state. Figure 3: Driver Software States spe2488ModuleOpen Idle spe2488ModuleClose Start spe2488ModuleStop spe2488ModuleStart spe2488ModuleClose Ready MODULE STATES Start spe2488Add spe2488Delete Present spe2488Reset spe2488Init spe2488Activate Inactive spe2488DeActivate PER-DEVICE STATES Active spe2488Reset Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 26 SPECTRA-2488 (PM5315) Driver Manual Software Architecture Module States The following is a description of the SPECTRA-2488 module states. See section 5.1 for a detailed description of the API functions that are used to change the module state. Start The driver module has not been initialized. In this state the driver does not hold any RTOS resources (e.g., memory and timers), has no running tasks, and performs no actions. Idle The driver module has been initialized successfully. The Module Initialization Vector (MIV) has been validated, the Module Data Block (MDB) has been allocated and loaded with current data, the per-device data structures have been allocated, and the RTOS has responded without error to all the requests sent to it by the driver. Ready This is the normal operating state for the driver module. This means that all RTOS resources have been allocated and the driver is ready for devices to be added. The driver module remains in this state while devices are in operation. Device States The following is a description of the SPECTRA-2488 per-device states. The state that is mentioned here is the software state as maintained by the driver, and not as maintained inside the device itself. See section 5.3 for a detailed description of the API functions that are used to change the per-device state. Start The device has not been initialized. In this state the device is unknown to the driver and performs no actions. There is a separate flow for each device that can be added, and they all start here. Present The device has been successfully added. A Device Data Block (DDB) has been associated to the device and updated with the user context; and a device handle has been given to the user. In this state, the device performs no actions. Inactive In this state the device is configured, but all data functions have been de-activated including interrupts and alarms, and status and statistics functions. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 27 SPECTRA-2488 (PM5315) Driver Manual Software Architecture Active This is the normal operating state for the device. In this state, either interrupt servicing or polling is enabled. 3.4 Processing Flows This section describes the main processing flows of the SPECTRA-2488 driver components. The flow diagrams presented here illustrate the sequence of operations that take place for different driver functions. The diagrams also serve as a guide to the application programmer by illustrating the sequence in which the application must invoke the driver API. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 28 SPECTRA-2488 (PM5315) Driver Manual Software Architecture Module Management The following diagram illustrates the typical function call sequences that occur when initializing or shutting down the SPECTRA-2488 driver module. Figure 4: Module Management Flow Diagram START Performs module level initialization of the driver. Validates the Module Initialization Vector (MIV). Allocates memory for the MDB and all its components (i.e. all the memory needed by the driver) and then initializes the contents of the MDB with the validated MIV. Performs module level startup of the driver. This involves allocating RTOS resources such as semaphores and timers and installing the ISR handler and DPR task. Register an initialization profile. This allows the user to store pre-defined parameter vectors that are validated ahead of time. When the deviceinitialization function is invoked only a profile number need to be passed. This method simplifies and expedites the above operations. Perform all device level functions here (add, init, activate, de-activate, reset, delete,...) spe2488ClrInitProfile De-register an initialization profile previously registered with the driver. spe2488ModuleOpen spe2488ModuleStart spe2488SetInitProfile spe2488ModuleStop Performs Module level shutdown of the driver. This involves deleting all devices currently installed and de-allocating all timers and semaphores as well as removing the ISR handler and DPR task. Performs module level shutdown of the driver. De-allocates all the driver's memory. spe2488ModuleClose END Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 29 SPECTRA-2488 (PM5315) Driver Manual Software Architecture Device Management The following figure shows the typical function call sequences that the driver uses to add, initialize, re-initialize, and delete the SPECTRA-2488 device. Figure 5: Device Management Flow Diagram START spe2488Add Detects the new device in hardware, assigns a DDB to the new device and stores the user's context for the device. Returns a device handle to the user. Applies a reset to the device and initializes the device registers and associated RAMs based on the DIV passed by the user. The user may only pass a profile number, which corresponds to a previously saved & validated set of configurations (by using spe2488SetInitProfile). spe2488Init spe2488Activate Prepares the device for normal operation by enabling interrupts and other global enables. ISR routines are installed when the module is started using sysSpe2488ISRHandlerInstall. The device is now operational and all other API can be invoked. spe2488Reset In order to re-initialize the device, reset the device using spe2488Reset and go through the initialization sequence again. spe2488DeActivate De-activates the device and removes it from normal operation. This involves disabling the device interrupts. ISR routines for this device are removed using sysSpe2488ISRHandlerRemove when the module is closed. Applies a software reset to the device to put it in its default startup state. spe2488Reset spe2488Delete Removes the device from the list of devices being controlled by the SPECTRA-2488 driver. This function de-allocates the device context information for the device being deleted. END Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 30 SPECTRA-2488 (PM5315) Driver Manual Software Architecture 3.5 Interrupt Servicing The SPECTRA-2488 driver services device interrupts using an Interrupt-Service Routine (ISR) that traps interrupts and a Deferred-Processing Routine (DPR) that actually processes the interrupt conditions and clears them. This lets the ISR execute quickly and exit. Most of the time-consuming processing of the interrupt conditions is deferred to the DPR by queuing the necessary interrupt-context information to the DPR task. The DPR function runs in the context of a separate task within the RTOS. Note: Since the DPR task processes potentially serious interrupt conditions, you should set the DPR task's priority higher than that of the application task interacting with the SPECTRA-2488 driver. The driver provides system-independent functions, spe2488ISR and spe2488DPR. You must fill in the corresponding system-specific functions, sysSpe2488ISRHandler and sysSpe2488DPRTask. The system-specific functions isolate the system-specific communication mechanism (between the ISR and DPR) from the system-independent functions, spe2488ISR and spe2488DPR. Figure 6 illustrates the interrupt service model used in the SPECTRA-2488 driver design. Figure 6: Interrupt Service Model Interrupt Context Information sysSpectra2ISRHandler spectra2ISR sysSpectra2DPRTask Indication Callbacks Application spectra2DPR Note: Instead of using an interrupt service model, you can use a polling service model in the SPECTRA-2488 driver to process the device's event-indication registers (see page 26). Calling spe2488ISR An interrupt handler function, which is system dependent, must call spe2488ISR. But first, the low-level interrupt-handler function must trap the device interrupts. You must implement this function to fit your own system. As a reference, an example implementation of the interrupt handler (sysSpe2488ISRHandler) appears on page 137. You can customize this example implementation to suit your needs. The interrupt handler that you implement (sysSpe2488ISRHandler) is installed in the interrupt vector table of the system processor. It is called when one or more SPECTRA-2488 devices interrupt the processor. The interrupt handler then calls spe2488ISR for each device in the active state that has interrupt processing enabled. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 31 SPECTRA-2488 (PM5315) Driver Manual Software Architecture The spe2488ISR function reads from the master interrupt-status registers and the miscellaneous interrupt-status registers of the SPECTRA-2488. If at least one valid interrupt condition is found, then spe2488ISR fills an Interrupt-Service Vector (ISV) with this status information as well as the current device Handle. The spe2488ISR function also clears and disables all of the device interrupts that have been detected. The sysSpe2488ISRHandler function is then responsible for sending this ISV buffer to the DPR task. Note: Normally you should save the status information for deferred processing by implementing a message queue. The interrupt handler sends the status information to the queue by the sysSpe2488ISRHandler. Calling spe2488DPR The sysSpe2488DPRTask function is a system-specific function that runs as a separate task within the RTOS. You should set the DPR task's priority higher than that of the application task(s) interacting with the SPECTRA-2488 driver. In the message-queue implementation model, this task has an associated message queue. The task waits for messages from the ISR on this message queue. When a message arrives, sysSpe2488DPRTask calls the DPR (spe2488DPR) with the received ISV. After that, spe2488DPR processes the status information and takes appropriate action based on the specific interrupt condition detected. The nature of this processing can differ from system to system. Therefore, spe2488DPR calls different indication callbacks for different interrupt conditions. Typically, you should implement these callback functions as simple message posting functions that post messages to an application task. However, you can implement the indication callback to perform processing within the DPR task context and return without sending any messages. In this case, ensure that this callback function does not call any API functions that would change the driver's state, such as spe2488Delete. Also, ensure that the callback function is non-blocking because the DPR task executes while SPECTRA-2488 interrupts are disabled. You can customize these callbacks to suit your system. See page 129 for example implementations of the callback functions. Note: Since the spe2488ISR and spe2488DPR routines themselves do not specify a communication mechanism, you have full flexibility in choosing a communication mechanism between the two. A convenient way to implement this communication mechanism is to use a message queue, which is a service that most RTOSs provide. You must implement the two system specific functions, sysSpe2488ISRHandler and sysSpe2488DPRTask. When the driver calls sysSpe2488ISRHandlerInstall, the application installs sysSpe2488ISRHandler in the interrupt vector table of the processor, and the sysSpe2488DPRTask function is spawned as a task by the application. The sysSpe2488ISRHandlerInstall function also creates the communication channel between sysSpe2488ISRHandler and sysSpe2488DPRTask. This communication channel is most commonly a message queue associated with the sysSpe2488DPRTask. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 32 SPECTRA-2488 (PM5315) Driver Manual Software Architecture Similarly, during the removal of interrupts, the driver removes sysSpe2488ISRHandler from the microprocessor's interrupt vector table and deletes the task associated with sysSpe2488DPRTask. As a reference, this manual provides example implementations of the interrupt installation and removal functions in Section 6.2. You can modify these functions to suit your specific needs. Calling spe2488Poll Instead of using an interrupt service model, you can use the polling service model in the SPECTRA-2488 driver to process the device's event-indication registers. Figure 7 illustrates the polling service model used in the SPECTRA-2488 driver design. Figure 7: Polling Service Model spe2488Poll Interrupt Context Information Indication Callbacks spe2488DPR Application spe2488ISR In polling mode, the application is responsible for calling spe2488Poll often enough to service any pending error or alarm conditions. When spe2488Poll is called, the spe2488ISR function is called internally. The spe2488ISR function reads from the master interrupt-status registers and the miscellaneous interrupt-status registers of the SPECTRA-2488. If at least one valid interrupt condition is found, then spe2488ISR fills an Interrupt-Service Vector (ISV) with this status information as well as the current device Handle. The spe2488ISR function also clears and disables all the device interrupts that have been detected. In polling mode, this ISV buffer is passed to the DPR task by calling spe2488DPR internally. 3.6 Initialization of the Device for Various Payload Mappings The SPECTRA-2488 driver allows you to configure the device for all legal payload mappings. Whether the device is used in single- or quad-mode, the Device Initialization Vector (DIV) provides 4 variables that fully describe the payload mapping: sts12csl, sts12c, tug3 and sts3c. Table 2 describes each of these variables in more details. The sts12csl variable introduces the concept of master/slave STS-12 slices. By specifying that a slice is a slave, you specify that it is part of a bigger payload, such as STS-24c, STS-36c or STS-48c. The first STS-12 slice of a STS-24c, STS-36c or STS-48c payload is the master slice while the remaining slices are the slaves. Note that a STS-12c slice is a master STS-12 slice with no slave. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 33 SPECTRA-2488 (PM5315) Driver Manual Software Architecture Table 2: Payload Mapping Parameters Field Name sts12csl[4] Field Type UINT1 Field Description This array of 4 elements allows you to configure each STM-4 slice as being part of a STS-24c, a STS-36c or a STS-48c payload. 1 = this STM-4 (STS-12) is a slave concatenated payload 0 = this is a master slice This array of 4 elements allows you to configure each STM-4 slice as being an STS12c or part of a bigger concatenated payload (STS-24c, STS-36c or STS-48c). 1 = this STM-4 (STS-12) is a concatenated payload 0 = this STM-4 (STS-12) is not a concatenated payload This array of 16 elements allows you to identify where the TUG-3s are located in the payload, if there are any. 1 = this STM-1 (STS-3) payload is a TUG3 0 = this STM-1 (STS-3) payload is not a TUG3 This array of 16 elements allows you to identify where the STS-3c are located in the payload, if there are any. 1 = this STS-3 payload is concatenated. 0 = this STS-3 payload is not concatenated. sts12c[4] UINT1 tug3[4][4] UINT1 sts3c[4][4] UINT1 The following tables provide some example configurations that should help you understand how to configure the driver for any legal payload mapping. Table 3 shows how to configure an all STS-1 payload. Table 4 and Table 5 provide examples of master/slave concatenation. Table 6 presents a mixed payload configuration. Note that an `x' inside a table indicates that the corresponding value is ignored. Table 3 provides the configuration that you should use for a payload that contains all STS-1s. In this example, all variables are set to 0 to indicate that there is no STS-12c, no TUG-3, and no STS-3c. This is the default configuration: all STS-1. Table 3: 48xSTS-1 Configuration Field Name i 1 2 3 4 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 34 SPECTRA-2488 (PM5315) Driver Manual Software Architecture j sts12csl[i] sts12c[i] tug3[i][j] sts3c[i][j] 1 0 0 0 0 2 3 4 1 0 0 2 3 4 1 0 0 2 3 4 1 0 0 2 3 4 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 4 x 3xSTS-1 4 x 3 x STS-1 4 x 3 x STS-1 4 x 3 x STS-1 Table 4 illustrates how to configure a STS-48c payload. The first slice has sts12c set to 1 and sts12csl set to 0. This indicates that it is the master slice of either a STS-12c, a STS-24c, a STS-36c or a STS-48c. The last three slices have both sts12c and sts12csl set to 1, which indicates that they are all slave slices. This table shows one master with three slaves: this is a STS-48c. Table 4: STS-48c Configuration Field Name i j sts12csl[i] sts12c[i] tug3[i][j] sts3c[i][j] 1 1 0 1 x x x x x x x x 2 3 4 2 1 1 1 x x x x x x x x 2 3 4 3 1 1 1 x x x x x x x x 2 3 4 4 1 1 1 x x x x x x x x 2 3 4 STS-48c Table 5 illustrates how to configure a STS-24c with two adjacent STS-12c. Slices 1, 2 and 4 have sts12c set to 1 and sts12csl set to 0. This indicates that they are master concatenated slices. Slice 3 has both sts12c and sts12csl set to 1, which indicates that it is a slave. There is a master, a master and a slave, and then another master: slice 1 is a STS-12c, slices 2 and 3 form a STS-24c, and slice 4 is a STS-12c. Table 5: STS-12c / STS-24c / STS-12c Configuration Field Name i j 1 1 2 3 4 2 1 2 3 4 3 1 2 3 4 4 1 2 3 4 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 35 SPECTRA-2488 (PM5315) Driver Manual Software Architecture Field Name i j 1 1 0 1 x x x x x x x x 2 3 4 2 1 0 1 x x x x x x x x 2 3 4 3 1 1 1 x x x x x x x x 2 3 4 4 1 0 1 x x x x x x x x 2 3 4 sts12csl[i] sts12c[i] tug3[i][j] sts3c[i][j] STS-12c STS-24c STS-12c Table 6 illustrates a mixed payload with a combination of STS-3c, STS-12c, TUG3 and STS-1. In the first slice, all variables are set to 0 except for sts3c. This is a slice that contains all STS-3c. Slice 2 has a 1 in sts12c but a 0 in sts12csl, which indicates a master concatenated slice. Slice 3 has both sts12c and sts12csl set to 0, and therefore slice 2 can only be a STS-12c. Slice 3 has tug3 and sts3c set to 1, this slice is all TUG-3s. Slice 4 has all its variables set to 0, which indicates that it is an all STS-1 slice. Table 6: 4xSTS-3c/STS-12c/4xTUG-3/12xSTS-1 Configuration Field Name I j sts12csl[i] sts12c[i] tug3[i][j] sts3c[i][j] 1 1 0 0 0 1 0 1 0 1 0 1 2 3 4 2 1 0 1 x x x x x x x x 2 3 4 3 1 0 0 1 x 1 x 1 x 1 x 2 3 4 4 1 0 0 0 0 0 0 0 0 0 0 2 3 4 4 x STS-3c STS-12c 4 x TUG3 4 x 3 x STS-1 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 36 SPECTRA-2488 (PM5315) Driver Manual Data Structures 4 DATA STRUCTURES This section describes the elements of the driver that configure or control its behavior and therefore should be of interest to the application programmer. Included here are the constants, variables, and structures that the SPECTRA-2488 device driver uses to store initialization, configuration, and statistics information. For more information on our naming conventions, the reader is referred to Appendix C. Note: All (STM-4, AU-3) arrays that are used to pass 4 STM-4 and 12 AU-3 information are shown as arrays of size [4][12] in this document. However, in the driver source code, these arrays are declared to be of size [4+1][12+1] with the zeroeth element left unused. For example, an sts12c[4] array shown in this document is declared in the source code as sts12c[4+1]. The zeroeth element, sts12c[0], is left unused. 4.1 Constants The following constants are used throughout the driver code: * SPE2488_MAX_DEVS: defines the maximum number of devices that can be supported by this driver. This constant must not be changed without a thorough analysis of the consequences to the driver code. SPE2488_MAX_INIT_PROFS: defines the maximum number of initialization profiles that can * * be added to this driver. This constant must not be changed without a thorough analysis of the consequences to the driver code. * * SPE2488_MOD_START, SPE2488_MOD_IDLE, SPE2488_MOD_READY - are the three possible Module states (stored in stateModule). SPE2488_START, SPE2488_PRESENT, SPE2488_ACTIVE, SPE2488_INACTIVE - are the four possible device states (stored in stateDevice). Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 37 SPECTRA-2488 (PM5315) Driver Manual Data Structures 4.2 Structures Passed by the Application These structures are defined for use by the application and are passed as arguments to functions within the driver. These structures are the Module Initialization Vector (MIV), the Device Initialization Vector (DIV) and the ISR mask. Module Initialization Vector: MIV Passed via the spe2488ModuleOpen call, this structure contains all of the information needed by the driver to initialize and connect to the RTOS. It contains the following fields: * maxDevs is used to inform the driver how many devices will be operating concurrently during this session. The number is used to calculate the amount of memory that will be allocated by the driver. The maximum value that can be passed is SPE2488_MAX_DEVS (see section 4.1). maxInitProfs is used to inform the driver of how many Initialization profiles can be saved * during this session. The number is used to calculate the amount of memory that will be allocated by the driver. The maximum value that can be passed is SPE2488_MAX_INIT_PROFS (see section 4.1). Table 7: SPECTRA-2488 Module Initialization Vector: sSPE2488_MIV Field Name perrModule maxDevs Field Type INT4 * UINT2 Field Description (pointer to) errModule (see description in the MDB) Maximum number of devices supported during this session Maximum number of initialization profiles maxInitProfs UINT2 Device Initialization Vector: DIV Passed via the spe2488Init call, this structure contains all of the information needed by the driver to initialize a SPECTRA-2488 device. This structure is also passed via the spe2488SetInitProfile call when used as an initialization profile. It contains the following fields: * * valid indicates that this initialization profile has been properly initialized and may be used by the user. This field should be ignored when the DIV is passed directly. pollISR is a flag that indicates the type of interrupt servicing the driver is to use. The choices are `polling' (SPE2488_POLL_MODE), and `interrupt driven' (SPE2488_ISR_MODE). When configured in polling, the Interrupt capability of the device is NOT used, and the user is responsible for calling spe2488Poll periodically. The actual processing of the event information is the same for both modes. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 38 SPECTRA-2488 (PM5315) Driver Manual Data Structures * cbackIO, cbackSOH, cbackLOH, cbackRPOH, cbackRPOHTU3, cbackTPOH, cbackDPGM and cbackAPGM are used to pass the address of application functions that will be used by the DPR to inform the application code of pending events. If these fields are set as NULL, then any events that might cause the DPR to `call back' the application will be processed during ISR processing but will be ignored by the DPR. Table 8: SPECTRA-2488 Device Initialization Vector: sSPE2488_DIV Field Name valid pollISR cbackIO Field Type UINT2 eSPE2488_POLL void * Field Description Indicates that this structure is valid Indicates the type of ISR / polling to do Address for the callback function for Input / Output (IO) Events Address for the callback function for Section Overhead (SOH) Events Address for the callback function for Line Overhead (LOH) Events Address for the callback function for Receive Path Overhead (RPOH) Events Address for the callback function for Receive Path Overhead TU3 (RPOH-TU3) Events Address for the callback function for Transmit Path Overhead (TPOH) Events Address for the callback function for DROP Bus PRBS Generator/Monitor (DPGM) Events Address for the callback function for ADD Bus PRBS Generator/Monitor (APGM) Events When non-zero, this STM-4 (STS-12) is a slave concatenated payload When non-zero, this STM-4 (STS-12) is a concatenated payload. When non-zero, this STM-1 (STS-3) payload is a TUG3. cbackSOH void * cbackLOH void * cbackRPOH void * cbackRPOHTU3 void * cbackTPOH void * cbackDPGM void * cbackAPGM void * sts12csl[4] UINT1 sts12c[4] UINT1 tug3[4][4] UINT1 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 39 SPECTRA-2488 (PM5315) Driver Manual Data Structures Field Name sts3c[4][4] Field Type UINT1 Field Description When non-zero, this STS-3 payload is concatenated. Signal failure configuration. Signal degrade configuration. Counter configuration. cfgSF[4] cfgSD[4] cfgCnt sSPE2488_CFG_SFSD sSPE2488_CFG_SFSD sSPE2488_CFG_CNT PRBS Generator and Monitor Configuration (CFG_PRBS) This structure contains all the fields needed to configure the PRBS generators and monitors. The same structure is used to configure a monitor or a generator; however, some fields are used to configure a generator only. They should be ignored when configuring a monitor. Table 9: PRBS Generator and Monitor Configuration: sSPE2488_CFG_PRBS Field Name enable amode Field Type UINT1 UINT1 Field Description When non-zero, enables the generator/monitor Configures for telecombus when zero, autonomous mode otherwise When non-zero, PRBS data is inverted When non-zero, indicates to monitor/generate B1 and E1. Expected B1 byte / B1 byte to transmit (E1 is the complement of this. Pattern type 0 for PRBS, 1 for sequential S bits to be inserted in bits 2 and 3 of H1. Only used in autonomous mode and when processing concatenated payloads. (Generator Only) LFSR seed (23 bits) invPrbs b1e1Ena b1 UINT1 UINT1 UINT1 seqPrbs s UINT1 UINT1 lfsrSeed UINT4 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 40 SPECTRA-2488 (PM5315) Driver Manual Data Structures Signal Failure/Signal Degrade Configuration (CFG_SFSD) This structure contains all the fields needed to configure the signal failure (SF) and signal degrade (SD) accumulation period and thresholds. Table 10: Counters Config: sSPE2488_CFG_SFSD Field Name enable accumPeriod Field Type UINT1 UINT4 Field Description Enables SF/SD bit error rate monitoring The number of 8 KHz frames used to accumulate the B2 error subtotal. Allowable number of B2 errors that can be accumulated during an evaluation window before a SF or SD threshold event is declared. The threshold for the declaration of the SF or SD alarm. The threshold of maximum B2 allowed errors for clearing the SF or SD alarm. When non-zero, the clearing window size is 8x that of the declaring window. Otherwise they are both of the same size. When non-zero, the number of accumulated B2 errors is limited to the saturation threshold. saturation UINT4 declaring clearing UINT4 UINT4 clearMode UINT1 satuMode UINT1 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 41 SPECTRA-2488 (PM5315) Driver Manual Data Structures Config Counters (CFG_CNT) The user passes this structure when invoking spe2488CfgStats. It allows the user to configure the behaviour of the device counts. Table 11: SPECTRA-2488 Statistic Counters: sSPE2488_CFG_CNT Field Name sohBipAccBlk[4] Field Type UINT1 Field Description Controls the accumulation of Section BIP errors. When non-zero, Section BIP errors are counted by block Controls the extraction and accumulation of Line REI errors from the M1 byte. When non-zero, Line REI are counted by block Controls the indication of Line REI errors. When non-zero, Line REI errors are counted by block Controls the indication of Line BIP errors. When non-zero, Line BIP errors are counted by block Controls the accumulation of Line BIP errors. When non-zero, Line BIP errors are counted by block Controls the extraction and accumulation of Path REI errors from the G1 byte. When non-zero, Path REI are counted by block Controls the indication of Path REI errors. When non-zero, Path REI errors are counted by block Controls the indication of Path BIP errors. When non-zero, Path BIP errors are counted by block Controls the accumulation of Path BIP errors. When non-zero, Path BIP errors are counted by block Controls the extraction and accumulation of Path REI errors from the G1 byte. When non-zero, Path REI are counted by block lohReiAccBlk[4] UINT1 lohReiCntBlk[4] UINT1 lohBipCntBlk[4] UINT1 lohBipAccBlk[4] UINT1 rpohReiAccBlk[4][12] UINT1 rpohReiCntBlk[4][12] UINT1 rpohBipCntBlk[4][12] UINT1 rpohBipAccBlk[4][12] UINT1 rpohReiAccBlkTu3[4][12] UINT1 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 42 SPECTRA-2488 (PM5315) Driver Manual Data Structures Field Name rpohReiCntBlkTu3[4][12] Field Type UINT1 Field Description Controls the indication of Path REI errors. When non-zero, Path REI errors are counted by block Controls the indication of Path BIP errors. When non-zero, Path BIP errors are counted by block Controls the accumulation of Path BIP errors. When non-zero, Path BIP errors are counted by block Controls the extraction and accumulation of Path REI errors from the G1 byte. When non-zero, Path REI are counted by block Controls the indication of Path REI errors. When non-zero, Path REI errors are counted by block Controls the indication of Path BIP errors. When non-zero, Path BIP errors are counted by block Controls the accumulation of Path BIP errors. When non-zero, Path BIP errors are counted by block rpohBipCntBlkTu3[4][12] UINT1 rpohBipAccBlkTu3[4][12] UINT1 tpohReiAccBlk[4][12] UINT1 tpohReiCntBlk[4][12] UINT1 tpohBipCntBlk[4][12] UINT1 tpohBipAccBlk[4][12] UINT1 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 43 SPECTRA-2488 (PM5315) Driver Manual Data Structures ISR Enable/Disable Mask Passed via the spe2488SetMask, the spe2488GetMask, and the spe2488ClearMask calls, this structure contains all the information needed by the driver to enable and disable any of the interrupts in the SPECTRA-2488 Table 12: SPECTRA-2488 ISR Mask: sSPE2488_MASK Field Name master[4] aparrerr[4] dropCoap addCoap sbipe[4] los[4] lof[4] oof[4] tiu[4] tim[4] sfber[4] sdber[4] lreie[4] lbipe[4] cossm[4] coaps[4] apsbf[4] lrdi[4] lais[4] Field Type UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 Field Description Master interrupt enable Add parity error DROP Change of active page ADD Change of active page Section BIP error Loss of Signal Loss of Frame Out of frame Section trace identifier unstable Section trace identifier mismatch Signal failure Signal degrade Line remote error indication error Line BIP error Change of SSM message Change of APS bytes APS byte failure Line remote defect indication Line alarm indication signal Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 44 SPECTRA-2488 (PM5315) Driver Manual Data Structures Field Name ptiu[4][12] ptim[4][12] ptiuTu3[4][12] ptimTu3[4][12] dropPaisc[4][12] dropPlopc[4][12] dropPais[4][12] dropPlop[4][12] dropPje[4][12] dropNje[4][12] dropPreie[4][12] dropPbipe[4][12] dropCoperdi[4][12] Field Type UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 Field Description Path trace identifier unstable Path trace identifier mismatch Path TU3 trace identifier unstable Path TU3 trace identifier mismatch DROP Path AIS concatenated DROP Path loss of pointer concatenated DROP Path AIS DROP Path Loss of pointer DROP Positive justification event DROP Negative justification event DROP Path remote error indication error DROP Path BIP error DROP Change of path enhanced remote defect indication DROP Path enhanced remote defect indication DROP Path remote defect indication DROP Path payload defect indication DROP Path unequipped DROP Path signal label mismatch DROP Path signal label unstable DROP Change of path signal label DROP positive pointer justification DROP negative pointer justification DROP FIFO overflow dropPerdi[4][12] dropPrdi[4][12] dropPpdi[4][12] dropPuneq[4][12] dropPslm[4][12] dropPslu[4][12] dropCopsl[4][12] dropPpj[4][12] dropNpj[4][12] dropFovr[4][12] UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 45 SPECTRA-2488 (PM5315) Driver Manual Data Structures Field Name dropFudr[4][12] dropMonErr[4][12] dropMonE1B1[4][12] dropMonSync[4][12] Field Type UINT2 UINT2 UINT2 UINT2 Field Description DROP FIFO underflow DROP monitor byte error DROP monitor change of B1/E1 DROP monitor change of synchronization state DROP Path loss of pointer DROP Path AIS DROP Path AIS concatenated DROP Path loss of pointer concatenated DROP Path AIS DROP Path Loss of pointer DROP Positive justification event DROP Negative justification event DROP Path remote error indication error DROP Path BIP error DROP Change of path enhanced remote defect indication DROP Path enhanced remote defect indication DROP Path remote defect indication DROP Path payload defect indication DROP Path unequipped DROP Path signal label mismatch DROP Path signal label unstable DROP Change of path signal label dropPloptr[4][12] dropPaisptr[4][12] dropPaiscTu3[4][12] dropPlopcTu3[4][12] dropPaisTu3[4][12] dropPlopTu3[4][12] dropPjeTu3[4][12] dropNjeTu3[4][12] dropPreieTu3[4][12] dropPbipeTu3[4][12] dropCoperdiTu3[4][12] UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 dropPerdiTu3[4][12] dropPrdiTu3[4][12] dropPpdiTu3[4][12] dropPuneqTu3[4][12] dropPslmTu3[4][12] dropPsluTu3[4][12] dropCopslTu3[4][12] UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 46 SPECTRA-2488 (PM5315) Driver Manual Data Structures Field Name dropPloptrTu3[4][12] dropPaisptrTu3[4][12] addPpj[4][12] addNpj[4][12] addFovr[4][12] addFudr[4][12] addMonErr[4][12] addMonE1B1[4][12] addMonSync[4][12] addPaisc [4][12] addPlopc [4][12] addPais [4][12] addPlop [4][12] addPje[4][12] addNje[4][12] addPreie[4][12] addPbipe[4][12] addCoperdi[4][12] Field Type UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 Field Description DROP Path loss of pointer DROP Path AIS ADD positive pointer justification ADD negative pointer justification ADD FIFO overflow ADD FIFO underflow ADD monitor byte error ADD monitor change of B1/E1 ADD monitor change of synchronization state ADD Path AIS concatenated ADD Path loss of pointer concatenated ADD Path AIS ADD Path Loss of pointer ADD Positive justification event ADD Negative justification event ADD Path remote error indication error ADD Path BIP error ADD Change of path enhanced remote defect indication ADD Path enhanced remote defect indication ADD Path remote defect indication ADD Path payload defect indication ADD Path unequipped ADD Path signal label mismatch addPerdi[4][12] addPrdi[4][12] addPpdi[4][12] addPuneq[4][12] addPslm[4][12] UINT2 UINT2 UINT2 UINT2 UINT2 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 47 SPECTRA-2488 (PM5315) Driver Manual Data Structures Field Name addPslu[4][12] addCopsl[4][12] Field Type UINT2 UINT2 Field Description ADD Path signal label unstable ADD Change of path signal label Statistics Counters (CNT) This structure as well as its component structures is used by the statistics collection APIs to retrieve the device counts. The user can either collect all statistics at once by using spe2488GetCnt or collect statistics from individual blocks using spe2488GetCntSOHLOH, spe2488GetCntRPOH, and/or spe2488GetCntTPOH. Table 13: SPECTRA-2488 Statistics Counters: sSPE2488_STAT_CNT Field Name cntSOH[4] Field Type sSPE2488_STAT_CNT_SOH Field Description Statistics counters of the Section Overhead (SOH) Statistics counters of the Line Overhead (LOH) Statistics counters of the Receive Path Overhead (RPOH) Statistics counters for the Transmit Path Overhead (TPOH) cntLOH[4] sSPE2488_STAT_CNT_LOH cntRPOH[4] sSPE2488_STAT_CNT_RPOH cntTPOH[4] sSPE2488_STAT_CNT_TPOH Section Overhead (SOH) Statistics Counters Table 14: SPECTRA-2488 Section Overhead Statistics Counters: sSPE2488_STAT_CNT_SOH Field Name sohBip Field Type UINT4 Field Description Section BIP errors counter Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 48 SPECTRA-2488 (PM5315) Driver Manual Data Structures Line Overhead (LOH) Statistics Counters Table 15: SPECTRA-2488 Line Overhead Status: sSPE2488_STAT_CNT_LOH Field Name lohBip lohRei Field Type UINT4 UINT4 Field Description Line BIP errors counter Line REI error counter Receive Path Overhead (RPOH) Statistics Counters Table 16: SPECTRA-2488 Receive Path Processing Statistics Counters: sSPE2488_STAT_CNT_RPOH Field Name rpohBip[12] rpohRei[12] rpohPosJustIn[12] Field Type UINT4 UINT4 UINT4 Field Description Path BIP error counter Path REI error counter Incoming positive pointer justification event counter Incoming negative pointer justification event counter Outgoing positive pointer justification event counter Outgoing negative pointer justification event counter Path TU3 BIP error counter Path TU3 REI error counter Incoming TU3 positive pointer justification event counter Incoming TU3 negative pointer justification event counter rpohNegJustIn[12] UINT4 rpohPosJustOut[12] UINT4 rpohNegJustOut[12] UINT4 rpohBipTu3[12] rpohReiTu3[12] rpohPosJustInTu3[12] UINT4 UINT4 UINT4 rpohNegJustInTu3[12] UINT4 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 49 SPECTRA-2488 (PM5315) Driver Manual Data Structures Field Name rpohDPGMPrse[12] Field Type UINT4 Field Description Number of PRBS byte errors detected since the last accumulation interval. Errors are only accumulated in the synchronized state and each PRBS data byte can have a maximum of 1 errors. Transmit Path Overhead (TPOH) Statistics Counters Table 17: SPECTRA-2488 Receive Path Processing Statistics Counters: sSPE2488_STAT_CNT_TPOH Field Name tpohBip[12] tpohRei[12] tpohPosJustIn[12] Field Type UINT4 UINT4 UINT4 Field Description Path BIP error counter Path REI error counter Incoming positive pointer justification event counter - transmit side Incoming negative pointer justification event counter - transmit side Outgoing positive pointer justification event counter - transmit side Outgoing negative pointer justification event counter - transmit side Number of PRBS byte errors detected since the last accumulation interval. Errors are only accumulated in the synchronized state and each PRBS data byte can have a maximum of 1 errors. tpohNegJustIn[12] UINT4 tpohPosJustOut[12] UINT4 tpohNegJustOut[12] UINT4 tpohAPGMPrse[12] UINT4 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 50 SPECTRA-2488 (PM5315) Driver Manual Data Structures Alarm Status (STATUS) These structures as well as their component structures are used by the statistics collection APIs to retrieve the current alarm status of the device. The user can either collect all statistics at once by using spe2488GetStatus or collect statistics from individual blocks using spe2488GetStatusIO, spe2488GetStatusSOHLOH, spe2488GetStatusRPOH, and/or spe2488GetStatusTPOH. Table 18: SPECTRA-2488 Alarm Status: sSPE2488_STATUS Field Name statIO statSOH[4] Field Type sSPE2488_STATUS_IO sSPE2488_STATUS_SOH Field Description Alarm status of the Input / Output (IO) Alarm status from the Section Overhead (SOH) Alarm status from the Line Overhead (LOH) Alarm status from the Receive Path Overhead (RPOH) Alarm status from the Transmit Path Overhead (TPOH) statLOH[4] sSPE2488_STATUS_LOH statRPOH[4] sSPE2488_STATUS_RPOH statTPOH[4] sSPE2488_STATUS_TPOH Input/Output Alarm Status (STATUS_IO) Table 19: SPECTRA-2488 Input / Output Alarm Status: sSPE2488_STATUS_IO Field Name rclkAct[4] Field Type UINT2 Field Description Monitors for low to high transitions on the internal receive clock of a given slice Monitors for low to high transitions on the internal transmit clock of a given slice Monitors for low to high transitions on the DROP system clock Monitors for low to high transitions on the ADD system clock Monitors for low to high transitions on the add J0J1 indication of a given slice tclkAct[4] UINT2 dropClkAct UINT2 addClkAct UINT2 addJ0J1Act[4] UINT2 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 51 SPECTRA-2488 (PM5315) Driver Manual Data Structures Field Name addPldAct[4] Field Type UINT2 Field Description Monitors for low to high transitions on the add payload indication of a given slice Monitors for low to high transitions on the add data bus of a given slice addDataAct[4] UINT2 Section Overhead Alarm Status (STATUS_SOH) Table 20: SPECTRA-2488 Section Overhead Alarm Status: sSPE2488_STATUS_SOH Field Name los lof oof tiu tim Field Type UINT2 UINT2 UINT2 UINT2 UINT2 Field Description LOS LOF OOF Section trace identifier unstable Section trace identifier mismatch Line Overhead Alarm Status (STATUS_LOH) Table 21: SPECTRA-2488 Line Overhead Alarm Status: sSPE2488_STATUS_LOH Field Name sfber sdber apsbf lrdi lais Field Type UINT2 UINT2 UINT2 UINT2 UINT2 Field Description SF SD APS byte failure Line RDI Line AIS Receive Path Overhead Alarm Status (STATUS_RPOH) Table 22: SPECTRA-2488 Receive Path Overhead Alarm Status: sSPE2488_STATUS_RPOH Field Name Field Type Field Description Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 52 SPECTRA-2488 (PM5315) Driver Manual Data Structures Field Name ptiu[12] ptim[12] dropPerdi[12] dropPrdi[12] dropPpdi[12] dropPuneq[12] dropPslm[12] dropPslu[12] dropMonE1B1[12] dropMonSync[12] dropPlopptr[12] dropPaisptr[12] dropPlopc[12] dropPaisc[12] dropPlop[12] dropPais[12] ptiuTu3[12] ptimTu3[12] dropPerdiTu3[12] dropPrdiTu3[12] dropPpdiTu3[12] dropPuneqTu3[12] dropPslmTu3[12] Field Type UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 Field Description Path trace identifier unstable Path trace identifier mismatch Path enhanced RDI Path RDI Path payload defect indication Path unequipped Path signal label mismatch Path signal label unstable Monitor B1/E1 error Monitor synchronization state change Path loss of pointer Path alarm indication signal Path loss of pointer concatenated Path alarm indication signal concatenated Path loss of pointer Path alarm indication signal Path trace identifier unstable Path trace identifier mismatch Path enhanced RDI Path RDI Path payload defect indication Path unequipped Path signal label mismatch Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 53 SPECTRA-2488 (PM5315) Driver Manual Data Structures Field Name dropPsluTu3[12] dropPlopptrTu3[12] dropPaisptrTu3[12] dropPlopcTu3[12] dropPaiscTu3[12] dropPlopTu3[12] dropPaisTu3[12] Field Type UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 Field Description Path signal label unstable Path loss of pointer Path alarm indication signal Path loss of pointer concatenated Path alarm indication signal concatenated Path loss of pointer Path alarm indication signal Transmit Path Overhead Alarm Status (STATUS_TPOH) Table 23: SPECTRA-2488 Transmit Path Overhead Alarm Status: sSPE2488_STATUS_TPOH Field Name addPerdi[12] addPrdi[12] addPpdi[12] addPuneq[12] addPslm[12] addPslu[12] addMonE1B1[12] addMonSync[12] addPlopc[12] addPaisc[12] addPlop[12] addPais[12] Field Type UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 UINT2 Field Description Path enhanced RDI Path RDI Path payload defect indication Path unequipped Path signal label mismatch Path signal label unstable Monitor B1/E1 error Monitor synchronization state change Path loss of pointer concatenated Path alarm indication signal concatenated Path loss of pointer Path alarm indication signal Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 54 SPECTRA-2488 (PM5315) Driver Manual Data Structures Time-Slot Structure: TSLOT Passed inside the Time-Slot Interchange (TSI) calls, this structure fully describes a single STS-1 timeslot. Table 24: SPECTRA-2488 Time-Slot: sSPE2488_TSLOT Field Name stm4 au3 Field Type UINT2 UINT2 Field Description STM-4 index AU3 index 4.3 Structures in the Driver's Allocated Memory These structures are defined and used by the driver and are part of the context memory allocated when the driver is opened. These structures are the Module Data Block (MDB) and the Device Data Block (DDB). Module Data Block: MDB The MDB is the top-level structure for the Module. It contains configuration data about the Module level code and pointers to configuration data about the device level codes. * errModule most of the Module API functions return a specific error code directly. When the returned code is SPE2488_FAILURE, this indicates that the top-level function was not able to carry the specified error code back to the application. Under those circumstances, the proper error code is recorded in this element. The element is the first in the structure so that the user can cast the MDB pointer into a INT4 pointer and retrieve the local error (this eliminates the need to include the MDB template into the application code). * * valid indicates that this structure has been properly initialized and may be read by the user. stateModule contains the current state of the Module and could be set to: SPE2488_MOD_START, SPE2488_MOD_IDLE or SPE2488_MOD_READY. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 55 SPECTRA-2488 (PM5315) Driver Manual Data Structures Table 25: SPECTRA-2488 Module Data Block: sSPE2488_MDB Field Name errModule valid Field Type INT4 UINT2 Field Description Global error indicator for module calls Indicates that this structure has been initialized Module state; can be one of the following IDLE or READY Maximum number of devices supported Number of devices currently registered Maximum number of initialization profiles (array of) Device Data Blocks (DDB) in context memory (array of) Initialization profiles in context memory stateModule eSPE2488_MOD_STATE maxDevs numDevs maxInitProfs pddb UINT2 UINT2 UINT2 sSPE2488_DDB * pinitProfs sSPE2488_DIV * Device Data Block: DDB The DDB is the top-level structure for each device. It contains configuration data about the device level code and pointers to configuration data about device level sub-blocks. * errDevice most of the device API functions return a specific error code directly. When the returned code is SPE2488_FAILURE, this indicates that the top-level function was not able to carry the specific error code back top the application. In addition, some device functions do not return an error code. Under those circumstances, the proper error code is recorded in this element. The element is the first in the structure so that the user can cast the DDB pointer to a INT4 pointer and retrieve the local error (this eliminates the need to include the DDB template in the application code). valid indicates that this structure has been properly initialized and may be read by the user. stateDevice contains the current state of the device and could be set to: SPE2488_START, SPE2488_PRESENT, SPE2488_ACTIVE or SPE2488_INACTIVE. usrCtxt is a value that can be used by the user to identify the device during the execution of the callback functions. It is passed to the driver when spe2488Add is called and returned to * * * the user in the DPV when a callback function is invoked. The element is unused by the driver itself and may contain any value. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 56 SPECTRA-2488 (PM5315) Driver Manual Data Structures Table 26: SPECTRA-2488 Device Data Block: sSPE2488_DDB Field Name errDevice valid Field Type INT4 UINT2 Field Description Global error indicator for device calls Indicates that this structure has been initialized Device State; can be one of the following SPE2488_PRESENT, SPE2488_ACTIVE or SPE2488_INACTIVE stateDevice eSPE2488_DEV_STATE baseAddr usrCtxt UINT2 * void * Base address of the device Stores the user's context for the device. It is passed as an input parameter when the driver invokes an application callback Profile number used at initialization Indicates the current type of ISR / polling Address for the callback function for Input / Output (IO) Events Address for the callback function for Section Overhead (SOH) Events Address for the callback function for Line Overhead (LOH) Events Address for the callback function for Receive Path Overhead (RPOH) Events Address for the callback function for Receive Path Overhead TU3 (RPOHTU3) Events Address for the callback function for Transmit Path Overhead (TPOH) Events Address for the callback function for DROP Bus PRBS Generator/Monitor (DPGM) Events profileNum pollISR UINT2 eSPE2488_POLL cbackIO void * cbackSOH void * cbackLOH void * cbackRPOH void * cbackRPOHTU3 void * cbackTPOH void * cbackDPGM void * Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 57 SPECTRA-2488 (PM5315) Driver Manual Data Structures Field Name cbackAPGM Field Type void * Field Description Address for the callback function for ADD Bus PRBS Generator/Monitor (APGM) Events When non-zero, this STM-4 (STS-12) is a slave concatenated payload When non-zero, this STM-4 (STS-12) is a concatenated payload When non-zero, this STM-1 (STS-3) payload is a TUG3 When non-zero, this STS-3 payload is concatenated DROP Bus PRBS Generator configuration block DROP Bus PRBS Monitor configuration block ADD Bus PRBS Generator configuration block ADD Bus PRBS Monitor configuration block Signal fail accumulation period, saturation threshold, declaring threshold, and clearing threshold parameters. Signal degrade accumulation period, saturation threshold, declaring threshold, and clearing threshold parameters. Counter configuration Version as it appears in JTAG ID Manufacter ID as it appears in JTAG ID part number as it appears in JTAG ID sts12csl[4] UINT1 sts12c[4] UINT1 tug3[4][4] UINT1 sts3c[4][4] UINT1 cfgDropGen[4][12] sSPE2488_CFG_PRBS cfgDropMon[4][12] sSPE2488_CFG_PRBS cfgAddGen[4][12] sSPE2488_CFG_PRBS cfgAddMon[4][12] sSPE2488_CFG_PRBS cfgSF[4] sSPE2488_CFG_SFSD cfgSD[4] sSPE2488_CFG_SFSD cfgCnt ver manuID partNum sSPE2488_CFG_CNT UINT2 UINT2 UINT2 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 58 SPECTRA-2488 (PM5315) Driver Manual Data Structures Field Name quad Field Type UINT2 Field Description Indicates the current state of the QUAD pin Application callback event thresholds Number of events that have occurred since the last time the thresholds have been reached. Interrupt Enable Mask threshold threshCntr sSPE2488_MASK sSPE2488_MASK mask sSPE2488_MASK 4.4 Structures Passed through RTOS Buffers Interrupt-Service Vector: ISV This buffer structure is used to capture the status of the device (during a poll or ISR processing) for use by the Deferred-Processing Routine (DPR). It is the template for all device registers that are involved in exception processing. It is the application's responsibility to create a pool of ISV buffers (using this template to determine the buffer's size) when the driver calls the user-supplied sysSpe2488BufferStart function. An individual ISV buffer is then obtained by the driver via sysSpe2488ISVBufferGet and returned to the `pool' via sysSpe2488ISVBufferRtn. Table 27: SPECTRA-2488 Interrupt-Service Vector: sSPE2488_ISV Field Name deviceHandle mask Field Type sSPE2488_HNDL sSPE2488_MASK Field Description Handle to the device in cause ISR mask filled with interrupt status Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 59 SPECTRA-2488 (PM5315) Driver Manual Data Structures Deferred-Processing Vector: DPV This block is used in two ways. First it is used to determine the size of the buffer that is required by the RTOS for use in the driver. Second it is the template for the data that is assembled by the DPR and then sent to the application code. Note: the application code is responsible for returning this buffer to the RTOS buffer pool. The DPR divides the SPECTRA-2488 into 7 sections: IO, SOH, LOH, RPOH, TPOH, DPGM, and APG.M. 7 User-supplied callback routines (one per section) are used to inform the application which section of the device has caused the event being reported. Table 28: SPECTRA-2488 Deferred-Processing Vector: sSPE2488_DPV Field Name event cause Field Type SPE2488_DPR_EVENT UINT2 Field Description Event being reported Reason for the Event 4.5 Global Variables Although most of the variables within the driver are not meant to be used by the application code, there is one global variable that can be of great use to the application code. spe2488Mdb: A global pointer to the Module Data Block (MDB). The content of this global variable should be considered read-only by the application. * errModule: This structure element is used to store an error code that specifies the reason for an API function's failure. The field is only valid for functions that do not return an error code or when a value of SPE2488_FAILURE is returned. * * 3). stateModule: This structure element is used to store the Module state (as shown in Figure pddb[ ]: This is an array of pointers to the individual Device Data Blocks. The user is cautioned that a DDB is only valid if the valid flag is set. Note that the array of DDBs is in no particular order. errDevice: This structure element is used to store an error code that specifies the reason for an API function's failure. The field is only valid for functions that do not return an error code or when a value of SPE2488_FAILURE is returned. Figure 3). stateDevice: This structure element is used to store the device state (as shown in Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 60 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface 5 APPLICATION PROGRAMMING INTERFACE This section provides a detailed description of each function that is a member of the SPECTRA2488 driver Application Programming Interface (API). API functions typically execute in the context of an application task. Note: These functions are not re-entrant. This means that two application tasks can not invoke the same API at the same time. However the driver protects its data structures from concurrent accesses by the application and the DPR task. 5.1 Module Management The module management is a set of API functions that are used by the Application to open, start, stop and close the driver module. These functions will take care of initializing the driver, allocating memory and all other RTOS resources needed by the driver. They are also used to change the module state. For more information on the module states, see the state diagram on page 26. For a typical module management flow diagram see page 29. Opening the Driver Module: spe2488ModuleOpen Performs module level initialization of the device driver. This involves allocating all of the memory needed by the driver and initializing the internal structures. Prototype Inputs Outputs Returns INT4 spe2488ModuleOpen(sSPE2488_MIV *pmiv) pmiv : (pointer to) Module Initialization Vector Places a pointer to errModule into the MIV passed by the Application. Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_MODULE_STATE SPE2488_ERR_INVALID_MIV SPE2488_ERR_MEM_ALLOC Valid States Side Effects SPE2488_MOD_START Changes the MODULE state to SPE2488_MOD_IDLE Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 61 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Closing the Driver Module: spe2488ModuleClose Performs module level shutdown of the driver. This involves deleting all of the devices being controlled by the driver (by calling spe2488Delete for each device) and de-allocating all the memory allocated by the driver. Prototype Inputs Outputs Returns Valid States Side Effects INT4 spe2488ModuleClose(void) None None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_MODULE_STATE SPE2488_MOD_IDLE, SPE2488_MOD_READY Changes the MODULE state to SPE2488_MOD_START Starting the Driver Module: spe2488ModuleStart Connects the RTOS resources to the driver. This involves allocating semaphores and timers, initializing buffers, and installing the ISR handler and DPR task. Upon successful return from this function, the driver is ready to add devices. Prototype Inputs Outputs Returns Valid States Side Effects INT4 spe2488ModuleStart(void) None None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_MODULE_STATE SPE2488_MOD_IDLE Changes the MODULE state to SPE2488_MOD_READY Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 62 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Stopping the Driver Module: spe2488ModuleStop Disconnects the RTOS resources from the driver. This involves de-allocating semaphores and timers, freeing-up buffers, and uninstalling the ISR handler and the DPR task. If there are any registered devices, spe2488Delete is called for each. Prototype Inputs Outputs Returns Valid States Side Effects INT4 spe2488ModuleStop(void) None None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_MODULE_STATE SPE2488_MOD_READY Changes the MODULE state to SPE2488_MOD_IDLE 5.2 Profile Management This section describes the functions that set, get and clear initialization profiles. Initialization profiles allow the user to store pre-defined Device Initialization Vectors (DIV) that are validated ahead of time. When the device initialization function is invoked, only a profile number need to be passed. This method simplifies and expedites the initialization process. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 63 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Setting an Initialization Profile: spe2488SetInitProfile Creates an initialization profile that is stored by the driver. A device can now be initialized by simply passing the initialization profile number. Prototype Inputs Outputs Returns INT4 spe2488SetInitProfile(sSPE2488_DIV *pProfile, UINT2 *pProfileNum) pProfile pProfileNum pProfileNum : (pointer to) initialization profile being added : (pointer to) allocated memory : profile number assigned by the driver Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_MODULE_STATE SPE2488_ERR_INVALID_ARG SPE2488_ERR_INVALID_PROFILE Valid States Side Effects SPE2488_MOD_IDLE, SPE2488_MOD_READY None Getting an Initialization Profile: spe2488GetInitProfile Gets the contents of an initialization profile, given its profile number. Prototype Inputs Outputs Returns INT4 spe2488GetInitProfile(UINT2 profileNum, sSPE2488_DIV *pProfile) profileNum pProfile pProfile : initialization profile number : (pointer to) allocated memory : contents of the corresponding profile Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_MODULE_STATE SPE2488_ERR_INVALID_ARG SPE2488_ERR_INVALID_PROFILE_NUM Valid States Side Effects SPE2488_MOD_IDLE, SPE2488_MOD_READY None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 64 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Clearing an Initialization Profile: spe2488ClrInitProfile Deletes an initialization profile, given its profile number. Prototype Inputs Outputs Returns INT4 spe2488ClrInitProfile(UINT2 profileNum) profileNum : initialization profile number None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_MODULE_STATE SPE2488_ERR_INVALID_PROFILE_NUM SPE2488_MOD_IDLE, SPE2488_MOD_READY Valid States Side Effects None 5.3 Device Management The device management is a set of API functions that are used by the Application to control the device. These functions take care of initializing a device in a specific configuration, enabling the device's general activity, as well as enabling interrupt processing for that device. They are also used to change the software state for that device. For more information on the device states, see the state diagram on page 26. For a typical device management flow diagram see page 30. Adding a Device: spe2488Add This verifies the presence of a new device in the hardware and then returns a handle back to the user. The device handle is passed as a parameter of most of the device API Functions. It is used by the driver to identify the device on which the operation is to be performed. Prototype Inputs sSPE2488_HNDL spe2488Add(void *usrCtxt, UINT2 *baseAddr, INT4 **pperrDevice) usrCtxt baseAddr pperrDevice : user context for this device : base address of the device : (pointer to) allocated memory Outputs ERROR code written to the MDB on failure: SPE2488_ERR_INVALID_ARG SPE2488_ERR_INVALID_MODULE_STATE SPE2488_ERR_DEVS_FULL SPE2488_ERR_DEV_ALREADY_ADDED SPE2488_ERR_INVALID_DEV Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 65 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface pperrDevice : (pointer to) errDevice (inside the DDB) Returns Success = Device Handle (to be used bas an argument to most of the SPECTRA-2488 APIs) Failure = NULL (pointer) SPE2488_MOD_READY Valid States Side Effects Changes the DEVICE state to SPE2488_PRESENT Deleting a Device: spe2488Delete This function is used to remove the specified device from the list of devices being controlled by the SPECTRA-2488 driver. Deleting a device involves invalidating the DDB for that device and releasing its associated device handle. Prototype Inputs Outputs Returns Valid States Side Effects INT4 spe2488Delete(sSPE2488_HNDL deviceHandle) deviceHandle : device Handle (from spe2488Add) None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_PRESENT, SPE2488_ACTIVE, SPE2488_INACTIVE Changes the DEVICE state to SPE2488_PRESENT Initializing a Device: spe2488Init This initializes the Device Data Block (DDB) associated with that device during spe2488Add; it also applies a soft reset to the device and configures it according to the DIV passed by the Application. If the DIV is passed as a NULL, the profile number is used. A profile number of zero indicates that all the register bits are to be left in their default state (after a soft reset). Note that the profile number is used only if the passed DIV is NULL. Prototype Inputs INT4 spe2488Init(sSPE2488_HNDL deviceHandle, sSPE2488_DIV *pdiv, UINT2 profileNum) deviceHandle pdiv profileNum : device Handle (from spe2488Add) : (pointer to) Device Initialization Vector : profile number (used only if pdiv is NULL) Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 66 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_DIV SPE2488_ERR_INVALID_PROFILE_NUM Valid States Side Effects SPE2488_PRESENT Changes the DEVICE state to SPE2488_INACTIVE Updating the Configuration of a Device: spe2488Update This updates the configuration of the device as well as the Device Data Block (DDB) associated with that device according to the DIV passed by the Application. The only difference between spe2488Update and spe2488Init is that no soft reset will be applied to the device. A profile number of zero is illegal. Prototype Inputs INT4 spe2488Update(sSPE2488_HNDL deviceHandle, sSPE2488_DIV *pdiv, UINT2 profileNum) deviceHandle pdiv profileNum : device Handle (from spe2488Add) : (pointer to) Device Initialization Vector : profile number (used only if pdiv is NULL) Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_DIV SPE2488_ERR_INVALID_PROFILE_NUM Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Resetting a Device: spe2488Reset This applies a software reset to the SPECTRA-2488 device. It also resets all the DDB contents (except for the user context). This function is typically called before re-initializing the device (via spe2488Init). Prototype Inputs Outputs Returns INT4 spe2488Reset(sSPE2488_HNDL deviceHandle) deviceHandle : device Handle (from spe2488Add) None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 67 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Valid States Side Effects SPE2488_PRESENT, SPE2488_ACTIVE, SPE2488_INACTIVE Changes the DEVICE state to SPE2488_PRESENT Activating a Device: spe2488Activate Restores the state of a device after a de-activate. Interrupts may be re-enabled. Prototype Inputs Outputs Returns INT4 spe2488Activate(sSPE2488_HNDL deviceHandle) deviceHandle : device Handle (from spe2488Add) None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_INACTIVE Valid States Side Effects Changes the DEVICE state to SPE2488_ACTIVE De-Activating a Device: spe2488DeActivate De-activates the device from operation. Interrupts are masked and the device is put into a quiet state via enable bits. Prototype Inputs Outputs Returns INT4 spe2488DeActivate(sSPE2488_HNDL deviceHandle) deviceHandle : device Handle (from spe2488Add) None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ACTIVE Valid States Side Effects Changes the DEVICE state to SPE2488_INACTIVE Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 68 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface 5.4 Device Read and Write Reading from Device Registers: spe2488Read This function is used to read a register of a specific SPECTRA-2488 device by providing the register number. It derives the actual address location based on the device handle and register number inputs. It then reads the contents of this address location using the system specific macro, sysSpe2488Read. Note that a failure to read returns a zero and any error indication is written to the associated DDB. Prototype Inputs Outputs UINT2 spe2488Read(sSPE2488_HNDL deviceHandle, UINT2 regNum) deviceHandle regNum : device Handle (from spe2488Add) : register number ERROR code written to the MDB: ERROR code written to the DDB: SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_REG Returns Valid States Side Effects Success = value read Failure = 0 SPE2488_PRESENT, SPE2488_ACTIVE, SPE2488_INACTIVE May affect registers that change after a read operation Writing to Device Registers: spe2488Write This function can be used to write to a register of a specific SPECTRA-2488 device by providing the register number. It derives the actual address location based on the device handle and register number inputs. It then writes the contents of this address location using the system specific macro, sysSpe2488Write. Note that a failure to write returns a zero and any error indication is written to the DDB. Prototype Inputs UINT2 spe2488Write(sSPE2488_HNDL deviceHandle, UINT2 regNum, UINT2 value) deviceHandle regNum value : device Handle (from spe2488Add) : register number : value to be written Outputs ERROR code written to the MDB: ERROR code written to the DDB: SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_REG Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 69 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Returns Valid States Side Effects Success = value written Failure = 0 SPE2488_PRESENT, SPE2488_ACTIVE, SPE2488_INACTIVE May change the configuration of the device Reading from a block of Device Registers: spe2488ReadBlock This function can be used to read a register block of a specific SPECTRA-2488 device by providing the starting register number and the size to read. It derives the actual start address location based on the device handle and starting register number inputs. It then reads the contents of this data block using multiple calls to the system specific macro, sysSpe2488Read. Note that a failure to read returns a zero and any error indication is written to the DDB. It is the user's responsibility to allocate enough memory for the block read. Prototype Inputs void spe2488ReadBlock(sSPE2488_HNDL deviceHandle, UINT2 startRegNum, UINT2 size, UINT2 *pblock) deviceHandle startRegNum size pblock : device Handle (from spe2488Add) : starting register number : size of the block to read : (pointer to) the block to read Outputs ERROR code written to the MDB: ERROR code written to the DDB: SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_REG SPE2488_ERR_INVALID_ARG pblock : (pointer to) the block read Returns Valid States Side Effects None SPE2488_PRESENT, SPE2488_ACTIVE, SPE2488_INACTIVE May affect registers that change after a read operation Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 70 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Writing to a Block of Device Registers: spe2488WriteBlock This function can be used to write to a register block of a specific SPECTRA-2488 device by providing the starting register number and the block size. It derives the actual starting address location based on the device handle and starting register number inputs. It then writes the contents of this data block using multiple calls to the system specific macro, sysSpe2488Write. A bit from the passed block is only modified in the device's registers if the corresponding bit is set in the passed mask. Note that any error indication is written to the DDB Prototype void spe2488WriteBlock(sSPE2488_HNDL deviceHandle, UINT2 startRegNum, UINT2 size, UINT2 *pblock, UINT2 *pmask) deviceHandle startRegNum size pblock pmask Inputs : device Handle (from spe2488Add) : starting register number : size of block to read : (pointer to) block to write : (pointer to) mask Outputs ERROR code written to the MDB: SPE2488_ERR_INVALID_DEV ERROR code written to the DDB: SPE2488_ERR_INVALID_REG SPE2488_ERR_INVALID_ARG Returns Valid States Side Effects None SPE2488_PRESENT, SPE2488_ACTIVE, SPE2488_INACTIVE May change the configuration of the device Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 71 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface 5.5 Input/Output The Input/Output section provides functions to configure and control the Time-Slot Interchange (TSI). Setting Timeslot Mapping Mode: spe2488IOSetMapMode Sets the global mapping mode of all TSIs in the specified device. Prototype Inputs INT4 spe2488IOSetMapMode(sSPE2488_HNDL deviceHandle, UINT1 direction, UINT1 tsiMode) deviceHandle direction tsiMode : device Handle (from spe2488Add) : direction (symmetry) 0 = Drop 1 = Add : TSI mapping mode 0 = dynamic mode 1 = bypass mode 2 = 12-48c mode 3 = 48c-12 mode Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Getting Timeslot Mapping Mode: spe2488IOGetMapMode Retrieves the global mapping mode of all TSIs in the specified device. Prototype Inputs INT4 spe2488IOGetMapMode(sSPE2488_HNDL deviceHandle, UINT1 direction, UINT1 *ptsiMode) deviceHandle direction ptsiMode : device Handle (from spe2488Add) : direction (symmetry) 0 = Drop 1 = Add : (pointer to) allocated memory Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 72 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Outputs ptsiMode : TSI mapping mode 0 = dynamic mode 1 = bypass mode 2 = 12-48c mode 3 = 48c-12 mode Returns Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Creating a Timeslot Mapping: spe2488IOMapSlot Maps a source timeslot to one or more destination timeslots. This function supports a unicast or a multicast mapping. Prototype INT4 spe2488IOMapSlot(sSPE2488_HNDL deviceHandle, UINT1 direction, UINT1 page, sSPE2488_TSLOT *psrcSlot, sSPE2488_TSLOT *pdestSlot, UINT1 numDestSlots) deviceHandle direction Inputs page psrcSlot pdestSlot numDestSlots : device Handle (from spe2488Add) : direction (symmetry) 0 = Drop 1 = Add : configuration page number : (pointer to) source timeslot : (pointer to) destination timeslot(s) : number of destination timeslots Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 73 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Determining if a Timeslot is being Multicasted: spe2488IOIsMulticast Informs the user of whether or not a source timeslot is being multicasted. Prototype INT4 spe2488IOIsMulticast(sSPE2488_HNDL deviceHandle, UINT1 direction, UINT1 page, sSPE2488_TSLOT *psrcSlot, UINT1 *pnumDestSlots) deviceHandle direction Inputs page psrcSlot pnumDestSlot : device Handle (from spe2488Add) : direction (symmetry) 0 = Drop 1 = Add : configuration page number : (pointer to) source timeslot : (pointer to) allocated memory : number of destination timeslot(s) Outputs Returns pnumDestSlot Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Getting Destination Timeslot(s): spe2488IOGetDestSlot Retrieves a list of destination timeslots mapped to a specified source timeslot. Prototype INT4 spe2488IOGetDestSlot(sSPE2488_HNDL deviceHandle, UINT1 direction, UINT1 page, sSPE2488_TSLOT *psrcSlot, sSPE2488_TSLOT *pdestSlot, UINT1 *pnumDestSlots) deviceHandle direction Inputs page psrcSlot pdestSlot pnumDestSlot : device Handle (from spe2488Add) : direction (symmetry) 0 = Drop 1 = Add : configuration page number : (pointer to) source timeslot : (pointer to) allocated memory : (pointer to) allocated memory : array of destination timeslot(s) : number of destination timeslot(s) Outputs pdestSlot pnumDestSlot Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 74 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Returns Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Getting Source Timeslot: spe2488IOGetSrcSlot Retrieves the source timeslot mapped to a specified destination timeslot. Prototype INT4 spe2488IOGetSrcSlot(sSPE2488_HNDL deviceHandle, UINT1 direction, UINT1 page, sSPE2488_TSLOT *pdestSlot, sSPE2488_TSLOT *psrcSlot) deviceHandle direction Inputs page pdestSlot psrcSlot : device Handle (from spe2488Add) : direction (symmetry) 0 = Drop 1 = Add : configuration page number : (pointer to) destination timeslot : (pointer to) allocated memory : source timeslot Outputs Returns psrcSlot Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 75 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Getting Active Configuration Page: spe2488IOGetPage Retrieves the currently active timeslot interchange configuration page (0 or 1). Prototype Inputs INT4 spe2488IOGetPage(sSPE2488_HNDL deviceHandle, UINT1 direction, UINT1 *ppage) deviceHandle direction ppage : device Handle (from spe2488Add) : direction (symmetry) 0 = Drop 1 = Add : (pointer to) allocated memory : active page number Outputs Returns ppage Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Setting Active Configuration Page: spe2488IOSetPage Sets the currently active timeslot interchange configuration page (0 or 1). Prototype Inputs INT4 spe2488IOSetPage(sSPE2488_HNDL deviceHandle, UINT1 direction, UINT1 page) deviceHandle direction page : device Handle (from spe2488Add) : direction (symmetry) 0 = Drop 1 = Add : active page number Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 76 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Inserting IDLE Data Pattern: spe2488IOInsertIdle Insert arbitrary idle data pattern into a given destination timeslot. Prototype Inputs INT4 spe2488IOSetPage(sSPE2488_HNDL deviceHandle, UINT1 direction, UINT1 page) deviceHandle direction page pdestSlot idle : device Handle (from spe2488Add) : direction (symmetry) 0 = Drop 1 = Add : page number : (pointer to) destination timeslot : idle data pattern (valid range: 0-2047) Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None 5.6 Section Overhead The Section Overhead section provides functions to control and monitor the Section Overhead processing. Read / Write access is given to the section trace message (J0). This message is compared with a configurable reference and mismatches are reported. In addition, section BIP-8 (B1) errors are accumulated in a counter that can be read and cleared, and Section Overhead alarms are detected and reported. For diagnostic purposes, errors can be introduced in the Section Overhead bytes. Selecting the Section Termination Mode: spe2488SOHTermination This function enables or disables the section termination of a particular STM-4. There are two possible modes: no section termination (SPE2488_NO_TERM) and section termination (SPE2488_TERM). When configured for section termination, the internal registers are used for section overhead insertion. Prototype Inputs INT4 spe2488SOHTermination(sSPE2488_HNDL deviceHandle, UINT2 stm4, eSPE2488_TERM mode) deviceHandle stm4 : device Handle (from spe2488Add) : STM-4 index Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 77 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface mode : section termination mode, one of the following: SPE2488_NO_TERM or SPE2488_TERM Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Reading and Setting the Section Trace Message (J0): spe2488SectionTraceMsg This function retrieves and sets the section trace message (J0) in the Sonet/SDH Section Trace Buffer. Configuring the transmit trace message will result in modifying the trace message transmitted even if this STM-4 is not configured for section termination. Note: It is the user's responsibility to ensure that the message pointer points to an area of memory large enough to hold the returned data. Prototype INT4 spe2488SectionTraceMsg(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 rw, UINT2 type, UINT2 length, UINT1* pJ0) deviceHandle stm4 rw type Inputs length pJ0 : device Handle (from spe2488Add) : STM-4 index : read/write flag, write if zero : type of access 0 = tx section trace 1 = rx accepted section trace 2 = rx captured section trace 3 = rx expected section trace : length of the message, 16 bytes long if zero 64 bytes long otherwise : (pointer to) the section trace message : section trace message Outputs Returns pJ0 Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 78 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Writing the J0 Byte: spe2488SOHWriteJ0 This function writes the J0 byte into the transmit Section Overhead. This will overwrite the J0 byte with the passed value, and the section trace message will be ignored. If this STM-4 is not configured for section termination, this function will have no effect on the Section Overhead. Prototype Inputs INT4 spe2488SOHWriteJ0(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT1 J0) deviceHandle stm4 J0 : device Handle (from spe2488Add) : STM-4 index : J0 byte to write Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Writing the Z0 Byte: spe2488SOHWriteZ0 This function writes the Z0 byte into the transmit Section Overhead. If this STM-4 is not configured for section termination, this function will have no effect on the Section Overhead. Prototype Inputs INT4 spe2488SOHWriteZ0(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT1 Z0) deviceHandle stm4 Z0 : device Handle (from spe2488Add) : STM-4 index : Z0 byte to write Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States SPE2488_ACTIVE, SPE2488_INACTIVE Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 79 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Side Effects None Writing the D1-D3 Byte: spe2488SOHWriteD1D3 This function writes the D1-D3 byte into the transmit Section Overhead. If this STM-4 is not configured for section termination, this function will have no effect on the Section Overhead. Prototype Inputs INT4 spe2488SOHWriteD1D3(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT1 D1D3) deviceHandle stm4 D1D3 : device Handle (from spe2488Add) : STM-4 index : D1D3 byte to write Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Writing the E1 Byte: spe2488SOHWriteE1 This function writes the E1 byte into the transmit Section Overhead. If this STM-4 is not configured for section termination, this function will have no effect on the Section Overhead. Prototype Inputs INT4 spe2488SOHWriteE1(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT1 valE1) deviceHandle stm4 valE1 : device Handle (from spe2488Add) : STM-4 index : E1 byte to write Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 80 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Writing the F1 Byte: spe2488SOHWriteF1 This function writes the F1 byte into the transmit Section Overhead. If this STM-4 is not configured for section termination, this function will have no effect on the Section Overhead. Prototype Inputs INT4 spe2488SOHWriteF1(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT1 F1) deviceHandle stm4 F1 : device Handle (from spe2488Add) : STM-4 index : F1 byte to write Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Forcing Out-of-Frame: spe2488SOHForceOOF This function forces the receive Section Overhead out-of-frame. Prototype Inputs Outputs Returns INT4 spe2488SOHForceOOF(sSPE2488_HNDL deviceHandle, UINT2 stm4) deviceHandle stm4 : device Handle (from spe2488Add) : STM-4 index None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG SPE2488_ERR_INVALID_DEVICE_STATE Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 81 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Forcing Errors in the Framing Bytes: spe2488SOHDiagFB This function enables the insertion of a single bit error continuously in the most significant bit (bit1) of the A1 Section Overhead framing byte. A1 bytes are set to 76H instead of F6H. Prototype Inputs INT4 spe2488SOHDiagFB(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 enable) deviceHandle stm4 enable : device Handle (from spe2488Add) : STM-4 index : flag to start/stop error insertion Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Forcing Section BIP-8 Errors: spe2488SOHDiagB1 This function enables the insertion of bit errors continuously in the B1 Section Overhead byte. Only those bits that are set in the passed mask are inverted. Prototype Inputs INT4 spe2488SOHDiagB1(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT1 maskB1, UINT2 enable) deviceHandle stm4 maskB1 enable : device Handle (from spe2488Add) : STM-4 index : mask identifying the bits to toggle in B1 : flag to start / stop error insertion Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 82 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Forcing Loss-of-Signal: spe2488SOHDiagLOS This function enables insertion of zeros in the transmit outgoing stream. Prototype Inputs INT4 spe2488SOHDiagLOS(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 enable) deviceHandle stm4 enable : device Handle (from spe2488Add) : STM-4 index : flag to start/stop error insertion Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None 5.7 Line Overhead The Line Overhead section is responsible for configuring and monitoring the line overhead on both receive and transmit sides. Read / Write access is given to the APS bytes (K1 and K2) and most of the other overhead bytes. Line BIP-8 (B2) errors and REI are accumulated in counters that can be read and cleared. Line overhead alarms are detected and reported. For diagnostic purposes, errors can be introduced in the line overhead bytes. Additional functions are provided to configure the device to automatically insert line RDI and AIS. Selecting the Line Termination Mode: spe2488LOHTermination This function enables or disables the line termination of a particular STM-4. There are three possible modes: no line termination (SPE2488_NO_TERM), line termination (SPE2488_TERM) and line termination with automatic alarm insertion (SPE2488_TERM_WITH_AUTO_INSERT). If selected, automatic error insertion in K1/K2 is performed. When configured for line termination, the internal registers are used for line overhead insertion. Prototype Inputs INT4 spe2488LOHTermination(sSPE2488_HNDL deviceHandle, UINT2 stm4, eSPE2488_TERM mode) deviceHandle stm4 mode : device Handle (from spe2488Add) : STM-4 index : line termination mode, one of the following: SPE2488_NO_TERM, SPE2488_TERM or Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 83 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface SPE2488_TERM_WITH_AUTO_INSERT Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Configuring Signal Fail (SF) and Signal Degrade (SD): spe2488LOHCfgSFSD This function configures the Signal Fail and Signal Degrade bit error rate monitoring capabilities of the SPECTRA-2488. Prototype INT4 spe2488LOHCfgSFSD(sSPE2488_HNDL deviceHandle, UINT2 stm4, sSPE2488_CFG_SFSD *pcfgSF, sSPE2488_CFG_SFSD *pcfgSD) deviceHandle stm4 pcfgSF pcfgSD Inputs : device Handle (from spe2488Add) : STM-4 index : (pointer to) SF configuration : (pointer to) SD configuration Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 84 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Reading the Received K1 and K2 Bytes: spe2488LOHReadK1K2 This function reads the K1 and K2 bytes from the received line overhead. Prototype Inputs INT4 spe2488LOHReadK1K2(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT1 *pK1, UINT1 *pK2) deviceHandle stm4 pK1 pK2 pK1 pK2 : device Handle (from spe2488Add) : STM-4 index : (pointer to) allocated memory : (pointer to) allocated memory : K1 byte read : K2 byte read Outputs Returns Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 85 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Writing the Transmitted K1 and K2 Bytes: spe2488LOHWriteK1K2 This function writes the K1 and K2 bytes into the transmit line overhead. If this STM-4 is not configured for line termination, this function will have no effect on the line overhead. Also, it this STM-4 is configured for automatic error insertion, the K1/K2 bytes are automatically generated by the device and this function has no effect. Prototype Inputs INT4 spe2488LOHWriteK1K2(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT1 K1, UINT1 K2) deviceHandle stm4 K1 K2 : device Handle (from spe2488Add) : STM-4 index : K1 byte to write : K2 byte to write Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 86 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Writing the D4-D12 Byte: spe2488LOHWriteD4D12 This function writes the D4-D12 bytes into the transmit line overhead. If this STM-4 is not configured for line termination, this function will have no effect on the line overhead. Prototype Inputs INT4 spe2488LOHWriteD4D12(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT1 D4D12) deviceHandle stm4 D4D12 : device Handle (from spe2488Add) : STM-4 index : D4D12 byte to write Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Reading the S1 Byte: spe2488LOHReadS1 This function reads the S1 byte from the receive line overhead. Prototype Inputs INT4 spe2488LOHReadS1(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT1 *pS1) deviceHandle stm4 pS1 pS1 : device Handle (from spe2488Add) : STM-4 index : (pointer to) allocated memory : S1 byte read Outputs Returns Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 87 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Writing the S1 Byte: spe2488LOHWriteS1 This function writes the S1 byte into the transmit line overhead. If this STM-4 is not configured for line termination, this function will have no effect on the line overhead. Prototype Inputs INT4 spe2488LOHWriteS1(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT1 S1) deviceHandle stm4 S1 : device Handle (from spe2488Add) : STM-4 index : S1 byte to write Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Writing the Z1 Byte: spe2488LOHWriteZ1 This function writes the Z1 byte into the transmit line overhead. If this STM-4 is not configured for line termination, this function will have no effect on the line overhead. Prototype Inputs INT4 spe2488LOHWriteZ1(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT1 Z1) deviceHandle stm4 Z1 : device Handle (from spe2488Add) : STM-4 index : Z1 byte to write Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 88 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Writing the Z2 Byte: spe2488LOHWriteZ2 This function writes the Z2 byte into the transmit line overhead. If this STM-4 is not configured for line termination, this function will have no effect on the line overhead. Prototype Inputs INT4 spe2488LOHWriteZ2(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT1 Z2) deviceHandle stm4 Z2 : device Handle (from spe2488Add) : STM-4 index : Z2 byte to write Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Writing the E2 Byte: spe2488LOHWriteE2 This function writes the E2 byte into the transmit line overhead. If this STM-4 is not configured for line termination, this function will have no effect on the line overhead. Prototype Inputs INT4 spe2488LOHWriteE2(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT1 E2) deviceHandle stm4 E2 : device Handle (from spe2488Add) : STM-4 index : E2 byte to write Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 89 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Inserting Line AIS: spe2488LOHInsertLineAIS When the enable flag is set, this function forces a Line-AIS insertion. When the enable flag is not set, this function resumes normal processing. Prototype Inputs INT4 spe2488LOHInsertLineAIS(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 enable) deviceHandle stm4 enable : device Handle (from spe2488Add) : STM-4 index : flag to start / stop Line-AIS insertion Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Inserting Line Remote Defect Indication: spe2488LOHInsertLineRDI This function enables the insertion of a transmit line remote defect indication (RDI). The Line RDI is inserted by transmitting the code 110 in bit positions 6, 7, and 8 of the K2 byte. Prototype Inputs INT4 spe2488LOHInsertLineRDI(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 enable) deviceHandle stm4 enable : device Handle (from spe2488Add) : STM-4 index : flag to start / stop Line RDI insertion Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 90 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Forcing Line BIP-8 Errors: spe2488LOHDiagB2 This function enables the insertion of bit errors continuously in each of the line BIP-8 bytes (B2 bytes). Only those bits that are set in the passed mask are inverted. Prototype Inputs INT4 spe2488LOHDiagB2(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT1 maskB2, UINT2 enable) deviceHandle stm4 maskB2 enable : device Handle (from spe2488Add) : STM-4 index : mask identifying the bits to toggle in B2 : flag to start / stop B2 error insertion Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 91 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Forcing Errors in the Payload Pointer: spe2488LOHDiagH1H2 This function enables the insertion of errors continuously in the payload pointer bytes (H1 and H2 bytes). Only those bits that are set in the passed mask are inverted. Prototype INT4 spe2488LOHDiagH1H2(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT1 maskH1, UINT1 maskH2, UINT2 enable) deviceHandle stm4 maskH1 maskH2 enable Inputs : device Handle (from spe2488Add) : STM-4 index : mask identifying the bits to toggle in H1 : mask identifying the bits to toggle in H2 : flag to start / stop error insertion Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None 5.8 Path Overhead The Path Overhead section configures and monitors the Path Overhead on both receive and transmit sides. Read / Write access is given to the path trace message (J1) and the path signal label (C2). Both are compared with a configurable reference and mismatches are reported. Path BIP-8 (B3) errors and REI are accumulated in a counter that can be read and cleared. Path Overhead alarms are detected and reported. For diagnostic purposes, errors can be introduced in the Path Overhead bytes. Additional functions are provided to configure the device to automatically insert path RDI, path enhanced RSI, and path AIS. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 92 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Selecting the Path Termination Mode: spe2488POHTermination This function enables or disables the path termination of a particular (STM-4, AU3) slice. There are three possible modes: no path termination (SPE2488_NO_TERM), path termination (SPE2488_TERM) and path termination with automatic alarm insertion (SPE2488_TERM_WITH_AUTO_INSERT). If selected, automatic error insertion in G1 is performed. When configured for path termination, the internal registers are used for path overhead insertion. Prototype INT4 spe2488POHTermination(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, eSPE2488_TERM mode) deviceHandle stm4 au3 mode Inputs : device Handle (from spe2488Add) : STM-4 index : AU-3 index : path termination mode, one of the following: SPE2488_NO_TERM, SPE2488_TERM or SPE2488_TERM_WITH_AUTO_INSERT Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 93 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Selecting the TU3 Path Termination Mode: spe2488POHTerminationTU3 This function enables or disables the TU3 path termination of a particular (STM-4, AU3) slice. There are three possible modes: no TU3 path termination (SPE2488_NO_TERM), TU3 path termination (SPE2488_TERM) and TU3 path termination with automatic alarm insertion (SPE2488_TERM_WITH_AUTO_INSERT). If selected, automatic error insertion in G1-TU3 is performed. When configured for TU3 path termination, the internal registers are used for TU3 path overhead insertion. Prototype INT4 spe2488POHTerminationTU3(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, eSPE2488_TERM mode) deviceHandle stm4 au3 mode Inputs : device Handle (from spe2488Add) : STM-4 index : AU-3 index : path-TU3 termination mode, one of the following: SPE2488_NO_TERM, SPE2488_TERM or SPE2488_TERM_WITH_AUTO_INSERT Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Retrieving and Setting the Path Trace Messages: spe2488PathTraceMsg This function retrieves and sets the current path trace message (J1) in the Sonet/SDH Path Trace Buffer. Note: It is the user's responsibility to make sure that the message pointer points to an area of memory large enough to hold the returned data. Prototype INT4 spe2488PathTraceMsg(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT2 rw, UINT2 type, UINT2 length, UINT1* pJ1) deviceHandle stm4 au3 rw type Inputs : device Handle (from spe2488Add) : STM-4 index : AU-3 index : read/write flag, write if zero : type of access 0 = tx path trace Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 94 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface length pJ1 1 = rx accepted path trace 2 = rx captured path trace 3 = rx expected path trace : length of the message, 16 bytes long if zero 64 bytes long otherwise : (pointer to) the path trace message : updated path trace message Outputs Returns pJ1 Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Retrieving and Setting the TU3 Path Trace Messages: spe2488PathTraceMsgTU3 This function retrieves and sets the current TU3 path trace message (J1-TU3) in the Sonet/SDH Path Trace Buffer. Note: It is the user's responsibility to make sure that the message pointer points to an area of memory large enough to hold the returned data. This function can only be called if this slice was configured as a TUG3. Prototype INT4 spe2488PathTraceMsgTU3(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT2 rw, UINT2 type, UINT2 length, UINT1* pJ1) deviceHandle stm4 au3 rw type Inputs length pJ1 : device Handle (from spe2488Add) : STM-4 index : AU-3 index : read/write flag, write if zero : type of access 0 = tx TU3 path trace 1 = rx accepted TU3 path trace 2 = rx captured TU3 path trace 3 = rx expected TU3 path trace : length of the TU3 message, 16 bytes long if zero 64 bytes long otherwise : (pointer to) the TU3 path trace message : updated TU3 path trace message Outputs Returns pJ1 Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 95 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Receive Path Overhead (RPOH) Retrieving and Setting the Received Path Signal Label: spe2488RPOHPathSignalLabel This function retrieves the captured and accepted path signal label (C2) and sets the expected path signal label on the receive link. Prototype INT4 spe2488RPOHPathSignalLabel(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT2 rw, UINT2 type, UINT1* pPSL) deviceHandle stm4 au3 rw type Inputs pPSL : device Handle (from spe2488Add) : STM-4 index : AU-3 index : read/write flag, write if zero : type of access 1 = rx accepted path signal label 2 = rx captured path signal label 3 = rx expected path signal label : (pointer to) path signal label : updated path signal label Outputs Returns pPSL Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 96 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Retrieving and Setting the TU3 Path Signal Label: spe2488PathSignalLabelTU3 This function retrieves the captured and accepted path signal label (C2-TU3) and sets the expected TU3 path signal label on the receive link. Prototype INT4 spe2488PathSignalLabelTU3(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT2 rw, UINT2 type, UINT1* pPSL) deviceHandle stm4 au3 rw type Inputs pPSL : device Handle (from spe2488Add) : STM-4 index : AU-3 index : read/write flag, write if zero : type of access 1 = rx accepted path signal label 2 = rx captured path signal label 3 = rx expected path signal label : (pointer to) path signal label : updated path signal label Outputs Returns pPSL Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Forcing Loss-of-Pointer: spe2488RPOHDiagLOP This function forces the downstream pointer processing to enter the Loss of Pointer (LOP) state. It does so by inverting the new data flag (NDF) field of the payload pointer that is inserted in the DROP bus. Prototype Inputs INT4 spe2488RPOHDiagLOP(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT2 enable) deviceHandle stm4 au3 enable : device Handle (from spe2488Add) : STM-4 index : AU-3 index : flag to start/stop NDF inversion Outputs Returns None Success = SPE2488_SUCCESS F il SPE2488 ERR INVALID DEV Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 97 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Forcing Pointer Justification: spe2488RPOHDiagPJ This function diagnoses the downstream pointer processing elements so that there are correct reactions to pointer justification events. In addition, the function either forces positive or negative justification events or disables the generation of any pointer justification element. Prototype Inputs INT4 spe2488RPOHDiagPJ(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT2 enable, INT1 type) deviceHandle stm4 au3 enable type : device Handle (from spe2488Add) : STM-4 index : AU-3 index : flag to start/stop diagnostic : type of pointer justification event: 0 = no pointer justification -1 = negative pointer justification +1 = positive pointer justification Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Retrieving the Received Pointer Value: spe2488RPOHReadPtr Retrieves the pointer value received in the H1 and H2 bytes of the received stream. Prototype Inputs INT4 spe2488RPOHReadPtr(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT2 *pcptr) deviceHandle stm4 au3 pcptr : device Handle (from spe2488Add) : STM-4 index : AU-3 index : (pointer to) allocated memory Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 98 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Outputs Returns pcptr : current pointer value received in H1-H2 Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Retrieving the Received TU3 Pointer Value: spe2488RPOHReadPtrTU3 Retrieves the pointer value received in the H1-TU3 and H2-TU3 bytes of the received stream. This function can only be called if this slice was configured as a TUG3. Prototype Inputs INT4 spe2488RPOHReadPtrTU3(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT2 *pcptr) deviceHandle stm4 au3 pcptr pcptr : device Handle (from spe2488Add) : STM-4 index : AU-3 index : (pointer to) allocated memory : current pointer value received in H1-H2 Outputs Returns Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 99 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Transmit Path Overhead (TPOH) Retrieving and Setting the Transmit Path Signal Label: spe2488TPOHPathSignalLabel This function retrieves the captured and accepted path signal label (C2) and sets the expected path signal label on the transmit link. Prototype INT4 spe2488TPOHPathSignalLabel(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT2 rw, UINT2 type, UINT1* pPSL) deviceHandle stm4 au3 rw type Inputs pPSL : device Handle (from spe2488Add) : STM-4 index : AU-3 index : read/write flag, write if zero : type of access 1 = rx accepted path signal label 2 = rx captured path signal label 3 = rx expected path signal label : (pointer to) path signal label : updated path signal label Outputs Returns pPSL Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Forcing Path AIS: spe2488TPOHInsertPAIS This function enables the insertion of the path alarm indication signal (PAIS) in the transmit stream. The synchronous payload envelope and the pointer bytes (H1 - H3) are set to all ones. Prototype Inputs INT4 spe2488TPOHInsertPAIS(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT2 enable) deviceHandle stm4 au3 enable : device Handle (from spe2488Add) : STM-4 index : AU-3 index : flag to start/stop PAIS insertion Outputs None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 100 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Returns Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Forcing Path BIP-8 Errors: spe2488TPOHDiagB3 This function enables the inversion of the path BIP-8 byte (B3) in the transmit stream. Only those bits that are set in the passed mask are inverted. Prototype Inputs INT4 spe2488TPOHDiagB3(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT1 maskB3, UINT2 enable) deviceHandle stm4 au3 maskB3 enable : device Handle (from spe2488Add) : STM-4 index : AU-3 index : mask identifying the bits to toggle in B3 : flag to start/stop B3 inversion Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Forcing TU3 Path BIP-8 Errors: spe2488TPOHDiagB3TU3 This function enables the inversion of the TU3 path BIP-8 byte (B3) in the transmit stream. Only those bits that are set in the passed mask are inverted. This function can only be called if this slice was configured as a TUG3. Prototype Inputs INT4 spe2488TPOHDiagB3TU3(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT1 maskB3, UINT2 enable) deviceHandle stm4 au3 maskB3 enable : device Handle (from spe2488Add) : STM-4 index : AU-3 index : mask identifying the bits to toggle in B3 : flag to start/stop B3 inversion Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 101 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Writing the Path Remote Error Indication Count: spe2488TPOHInsertPREI This function inserts the path remote error indication count passed in argument inside the path status byte. If this (STM-4, AU3) is not configured for path termination, this function will have no effect on the Path Overhead. Prototype Inputs INT4 spe2488TPOHInsertPREI(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT1 PREI) deviceHandle stm4 au3 prei : device Handle (from spe2488Add) : STM-4 index : AU-3 index : PREI value Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 102 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Writing the TU3 Path Remote Error Indication Count: spe2488TPOHInsertPREITU3 This function inserts the TU3 path remote error indication count passed in argument inside the path status byte. This function can only be called if this slice was configured as a TUG3. If this (STM-4, AU3) is not configured for path termination, this function will have no effect on the Path Overhead. Prototype Inputs INT4 spe2488TPOHInsertPREITU3(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT1 PREI) deviceHandle stm4 au3 prei : device Handle (from spe2488Add) : STM-4 index : AU-3 index : PREI value Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Controlling Pointer Justification: spe2488TPOHDiagPJ This function diagnoses the downstream pointer processing elements for correct reaction to pointer justification events. It can either force positive or negative stuff justification events or disable the generation of any pointer justification element. Prototype Inputs INT4 spe2488TPOHDiagPJ(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT2 enable, INT1 type) deviceHandle stm4 au3 enable type : device Handle (from spe2488Add) : STM-4 index : AU-3 index : flag to start/stop diagnostic : type of pointer justification event: 0 for no pointer justification -1 for negative +1 for positive Outputs Returns None Success = SPE2488_SUCCESS Fail re SPE2488 ERR INVALID DEV Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 103 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Writing the J1 Byte: spe2488TPOHWriteJ1 This function writes the J1 byte into the Transmit Path Overhead. If this (STM-4, AU3) is not configured for path termination, this function will have no effect on the Path Overhead. Prototype Inputs INT4 spe2488TPOHWriteJ1(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT1 J1) deviceHandle stm4 au3 J1 : device Handle (from spe2488Add) : STM-4 index : AU-3 index : J1 byte to write Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Writing the J1-TU3 Byte: spe2488TPOHWriteJ1TU3 This function writes the J1-TU3 byte into the transmit TU3 Path Overhead. This function can only be called if this slice was configured as a TUG3. If this (STM-4, AU3) is not configured for path termination, this function will have no effect on the Path Overhead. Prototype Inputs INT4 spe2488TPOHWriteJ1TU3(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT1 J1) deviceHandle stm4 au3 J1 : device Handle (from spe2488Add) : STM-4 index : AU-3 index : TU3 byte to write Outputs Returns None Success = SPE2488_SUCCESS F il SPE2488 ERR INVALID DEV Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 104 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Writing the C2 Byte: spe2488TPOHWriteC2 This function writes the C2 byte into the Transmit Path Overhead. If this (STM-4, AU3) is not configured for path termination, this function will have no effect on the Path Overhead. Prototype Inputs INT4 spe2488TPOHWriteC2(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT1 C2) deviceHandle stm4 au3 C2 : device Handle (from spe2488Add) : STM-4 index : AU-3 index : C2 byte to write Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Writing the C2-TU3 Byte: spe2488TPOHWriteC2TU3 This function writes the C2-TU3 byte into the transmit TU3 Path Overhead. This function can only be called if this slice was configured as a TUG3. If this (STM-4, AU3) is not configured for path termination, this function will have no effect on the Path Overhead. Prototype Inputs INT4 spe2488TPOHWriteC2TU3(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT1 C2) deviceHandle stm4 au3 C2 : device Handle (from spe2488Add) : STM-4 index : AU-3 index : C2 byte to write Outputs Returns None Success = SPE2488_SUCCESS F il SPE2488 ERR INVALID DEV Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 105 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Writing the F2 Byte: spe2488TPOHWriteF2 This function writes the F2 byte into the Transmit Path Overhead. If this (STM-4, AU3) is not configured for path termination, this function will have no effect on the Path Overhead. Prototype Inputs INT4 spe2488TPOHWriteF2(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT1 F2) deviceHandle stm4 au3 F2 : device Handle (from spe2488Add) : STM-4 index : AU-3 index : F2 byte to write Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 106 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Writing the F2-TU3 Byte: spe2488TPOHWriteF2TU3 This function writes the F2-TU3 byte into the transmit TU3 Path Overhead. This function can only be called if this slice was configured as a TUG3. If this (STM-4, AU3) is not configured for path termination, this function will have no effect on the Path Overhead. Prototype Inputs INT4 spe2488TPOHWriteF2TU3(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT1 F2) deviceHandle stm4 au3 F2 : device Handle (from spe2488Add) : STM-4 index : AU-3 index : F2 byte to write Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Writing the Z3 Byte: spe2488TPOHWriteZ3 This function writes the Z3 byte into the Transmit Path Overhead. If this (STM-4, AU3) is not configured for path termination, this function will have no effect on the Path Overhead. Prototype Inputs INT4 spe2488TPOHWriteZ3(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT1 Z3) deviceHandle stm4 au3 Z3 : device Handle (from spe2488Add) : STM-4 index : AU-3 index : Z3 byte to write Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 107 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Writing the Z3-TU3 Byte: spe2488TPOHWriteZ3TU3 This function writes the Z3-TU3 byte into the transmit TU3 Path Overhead. This function can only be called if this slice was configured as a TUG3. If this (STM-4, AU3) is not configured for path termination, this function will have no effect on the Path Overhead. Prototype Inputs INT4 spe2488TPOHWriteZ3TU3(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT1 Z3) deviceHandle stm4 au3 Z3 : device Handle (from spe2488Add) : STM-4 index : AU-3 index : Z3 byte to write Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Writing the Z4 Byte: spe2488TPOHWriteZ4 This function writes the Z4 byte into the Transmit Path Overhead. If this (STM-4, AU3) is not configured for path termination, this function will have no effect on the Path Overhead. Prototype Inputs INT4 spe2488TPOHWriteZ4(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT1 Z4) deviceHandle stm4 au3 Z4 : device Handle (from spe2488Add) : STM-4 index : AU-3 index : Z4 byte to write Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 108 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Writing the Z4-TU3 Byte: spe2488TPOHWriteZ4TU3 This function writes the Z4-TU3 byte into the transmit TU3 Path Overhead. This function can only be called if this slice was configured as a TUG3. If this (STM-4, AU3) is not configured for path termination, this function will have no effect on the Path Overhead. Prototype Inputs INT4 spe2488TPOHWriteZ4TU3(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT1 Z4) deviceHandle stm4 au3 Z4 : device Handle (from spe2488Add) : STM-4 index : AU-3 index : Z4 byte to write Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Writing the Z5 Byte: spe2488TPOHWriteZ5 This function writes the Z5 byte into the Transmit Path Overhead. If this (STM-4, AU3) is not configured for path termination, this function will have no effect on the Path Overhead. Prototype Inputs INT4 spe2488TPOHWriteZ5(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT1 Z5) deviceHandle stm4 au3 Z5 : device Handle (from spe2488Add) : STM-4 index : AU-3 index : Z5 byte to write Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 109 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Writing the Z5-TU3 Byte: spe2488TPOHWriteZ5TU3 This function writes the Z5-TU3 byte into the transmit TU3 Path Overhead. This function can only be called if this slice was configured as a TUG3. If this (STM-4, AU3) is not configured for path termination, this function will have no effect on the Path Overhead. Prototype Inputs INT4 spe2488TPOHWriteZ5TU3(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT1 Z5) deviceHandle stm4 au3 Z5 : device Handle (from spe2488Add) : STM-4 index : AU-3 index : Z5 byte to write Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Retrieving Current Transmit Pointer Value: spe2488TPOHReadPtr This function retrieves the pointer value being inserted in H1 and H2 bytes of the reansmit stream. Prototype Inputs INT4 spe2488TPOHReadPtr(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT2 *pcptr) deviceHandle stm4 au3 pcptr pcptr : device Handle (from spe2488Add) : STM-4 index : AU-3 index : (pointer to) allocated memory : current pointer value received in H1-H2 Outputs Returns Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 110 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Forcing AU Pointer Value: spe2488TPOHForceTxPtr This function enables insertion of the AU pointer value passed in argument into the H1 and H2 bytes of the transmit stream. It can only be called if this slice is in TU3 mode. Prototype INT4 spe2488TPOHForceTxPtr(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT2 enable, UINT2 aptr) deviceHandle stm4 au3 enable aptr Inputs : device Handle (from spe2488Add) : STM-4 index : AU-3 index : flag to start/stop generation : pointer value to insert in H1-H2 Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 111 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface 5.9 DROP/ADD Bus PRBS Generator and Monitor (DPGM / APGM) DROP Bus PRBS Generator and Monitor (DPGM) Configuring the PRBS Generator: spe2488DPGMGenCfg This function fully configures the Drop bus PRBS generator. Prototype INT4 spe2488DPGMGenCfg(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT2 type, sSPE2488_CFG_PRBS *pcfgPrbs) deviceHandle stm4 au3 type Inputs pcfgPrbs : device Handle (from spe2488Add) : STM-4 index : AU-3 index : type of payload 0 = STS-12 / STM-4 1 = STS-24 / STM-8 2 = STS-36 / STM-12 3 = STS-48 / STM-16 : PRBS configuration structure Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 112 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Configuring the PRBS Monitor: spe2488DPGMMonCfg This function fully configures the Drop bus PRBS monitor. Prototype INT4 spe2488DPGMMonCfg(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT2 type, sSPE2488_CFG_PRBS *pcfgPrbs) deviceHandle stm4 au3 type Inputs pcfgPrbs : device Handle (from spe2488Add) : STM-4 index : AU-3 index : type of payload 0 = STS-12 / STM-4 1 = STS-24 / STM-8 2 = STS-36 / STM-12 3 = STS-48 / STM-16 : PRBS configuration structure Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Forcing Bit Errors: spe2488DPGMGenForceErr This function forces bit errors in the inserted pseudo random bit sequence (PRBS). Thereafter, the MSB of the PRBS is inverted, inducing a single bit error. Prototype Inputs INT4 spe2488DPGMGenForceErr(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3) deviceHandle stm4 au3 : device Handle (from spe2488Add) : STM-4 index : AU-3 index Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 113 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Forcing a Resynchronization: spe2488DPGMMonResync This function forces the resynchronization of the monitor to the incoming pseudo random bit sequence (PRBS). The monitor will go out of synchronization and begin re-synchronizing the incoming PRBS payload. This will automatically force all slaves to resynchronize at the same time. Prototype Inputs INT4 spe2488DPGMMonResync(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3) deviceHandle stm4 au3 : device Handle (from spe2488Add) : STM-4 index : AU-3 index Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None ADD Bus PRBS Generator and Monitor (APGM) Configuring the PRBS Generator: spe2488APGMGenCfg This function fully configures the Add bus PRBS generator. Prototype INT4 spe2488APGMGenCfg(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT2 type, sSPE2488_CFG_PRBS *pcfgPrbs) deviceHandle stm4 au3 type Inputs : device Handle (from spe2488Add) : STM-4 index : AU-3 index : type of payload 0 = STS-12 / STM-4 1 = STS-24 / STM-8 2 = STS-36 / STM-12 3 = STS-48 / STM-16 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 114 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface pcfgPrbs : PRBS configuration structure Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Configuring the PRBS Monitor: spe2488APGMMonCfg This function fully configures the Add bus PRBS monitor. Prototype INT4 spe2488APGMMonCfg(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT2 type, sSPE2488_CFG_PRBS *pcfgPrbs) deviceHandle stm4 au3 type Inputs pcfgPrbs : device Handle (from spe2488Add) : STM-4 index : AU-3 index : type of payload 0 = STS-12 / STM-4 1 = STS-24 / STM-8 2 = STS-36 / STM-12 3 = STS-48 / STM-16 : PRBS configuration structure Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 115 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Forcing Bit Errors: spe2488APGMGenForceErr This function forces bit errors in the inserted pseudo random bit sequence (PRBS). Thereafter, the MSB of the PRBS is inverted, inducing a single bit error. Prototype Inputs INT4 spe2488APGMGenForceErr(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3) deviceHandle stm4 au3 : device Handle (from spe2488Add) : STM-4 index : AU-3 index Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Forcing a Resynchronization: spe2488APGMMonResync This function forces the resynchronization of the monitor to the incoming pseudo random bit sequence (PRBS). The monitor will go out of synchronization and begin re-synchronizing the incoming PRBS payload. This will automatically force all slaves to resynchronize at the same time. Prototype Inputs INT4 spe2488APGMMonResync(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3) deviceHandle stm4 au3 : device Handle (from spe2488Add) : STM-4 index : AU-3 index Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 116 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface 5.10 Interrupt Service Functions This section describes interrupt-service functions that perform the following tasks: * * * Set, get and clear the interrupt enable mask Read and process the interrupt-status registers Poll and process the interrupt-status registers See page 31 for an explanation of our interrupt servicing architecture. Configuring ISR Processing: spe2488ISRConfig This function allows the user to configure how ISR processing is to be handled: polling (SPE2488_POLL_MODE) or interrupt driven (SPE2488_ISR_MODE). If polling is selected, the user is responsible for calling periodically spe2488Poll to collect exception data form the device. Prototype Inputs Outputs Returns INT4 spe2488ISRConfig(sSPE2488_HNDL deviceHandle, UINT2 mode) deviceHandle mode : device Handle (from spe2488Add) : mode of operation None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_MODE Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Getting the Interrupt Status Mask: spe2488GetMask This function returns the contents of the interrupt mask registers of the SPECTRA-2488 device. Prototype Inputs Outputs Returns INT4 spe2488GetMask(sSPE2488_HNDL deviceHandle, sSPE2488_MASK *pmask) deviceHandle pmask pmask : device Handle (from spe2488Add) : (pointer to) mask structure : (pointer to) updated mask structure Success = SPE2488_SUCCESS F il SPE2488 ERR INVALID DEV Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 117 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Setting the Interrupt Enable Mask: spe2488SetMask This function sets the contents of the interrupt mask registers of the SPECTRA-2488 device. Any bits that are set in the passed structure are set in the associated SPECTRA-2488 registers. Prototype Inputs Outputs Returns INT4 spe2488SetMask(sSPE2488_HNDL deviceHandle, sSPE2488_MASK *pmask) deviceHandle pmask : device Handle (from spe2488Add) : (pointer to) mask structure None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE May change the operation of the ISR / DPR Clearing the Interrupt Enable Mask: spe2488ClearMask This function clears individual interrupt bits and registers in the SPECTRA-2488 device. Any bits that are set in the passed structure are cleared in the associated SPECTRA-2488 registers. Prototype Inputs Outputs Returns INT4 spe2488ClearMask(sSPE2488_HNDL deviceHandle, sSPE2488_MASK *pmask) deviceHandle pmask : device Handle (from spe2488Add) : (pointer to) mask structure None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States SPE2488_ACTIVE, SPE2488_INACTIVE Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 118 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Side Effects May change the operation of the ISR / DPR Polling the Interrupt Status Registers: spe2488Poll This function commands the driver to poll the interrupt registers in the device. The call will fail unless the device was initialized (via spe2488Init) or configured (via spe2488ISRConfig) into polling mode. Prototype Inputs Outputs Returns INT4 spe2488Poll(sSPE2488_HNDL deviceHandle) deviceHandle : device Handle (from spe2488Add) None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_MODE Valid States Side Effects SPE2488_ACTIVE None Interrupt-Service Routine: spe2488ISR This function reads the state of the interrupt registers in the SPECTRA-2488 and stores them in an ISV. Performs whatever functions are needed to clear the interrupt, from simply clearing bits to complex functions. This routine is called by the application code, from within sysSpe2488ISRHandler. If ISR mode is configured all interrupts that were detected are disabled and the ISV is returned to the Application. Note that the Application is then responsible for sending this buffer to the DPR task. If polling mode is selected, no ISV is returned to the Application and the DPR is called directly with the ISV. Prototype Inputs Outputs Returns Valid States Side Effects void * spe2488ISR(sSPE2488_HNDL deviceHandle) deviceHandle : device Handle (from spe2488Add) None (pointer to) ISV buffer (to send to the DPR) or NULL (pointer) SPE2488_ACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 119 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Deferred-Processing Routine: spe2488DPR This function acts on data contained in the passed ISV, allocates one or more DPV buffers (via sysSpe2488DPVBufferGet) and invokes one or more callbacks (if defined and enabled). This routine is called by the application code, within sysSpe2488DPRTask. Note that the callbacks are responsible for releasing the passed DPV. It is recommended that it be done as soon as possible to avoid running out of DPV buffers. Prototype Inputs Outputs Returns Valid States Side Effects void spe2488DPR(sSPE2488_ISV *pisv) pisv : (pointer to) ISV buffer None None SPE2488_ACTIVE None Setting the Thresholds for Callbacks: spe2488SetThresh This function sets the number of events that must be received (thresholds) before those events are reported via the callbacks. Prototype Inputs Outputs Returns INT4 spe2488SetThresh(sSPE2488_HNDL deviceHandle, sSPE2488_MASK *pthreshold) deviceHandle pthreshold : device Handle (from spe2488Add) : (pointer to) threshold structure None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 120 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Getting the Thresholds for Callbacks: spe2488GetThresh This function sets the number of events that must be received (thresholds) before those events are reported via the callbacks. Prototype Inputs Outputs Returns INT4 spe2488GetThresh(sSPE2488_HNDL deviceHandle, sSPE2488_MASK *pthreshold) deviceHandle pthreshold pthreshold : device Handle (from spe2488Add) : (pointer to) allocated memory : threshold structure Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Getting the Event Counters: spe2488GetThreshCntr This function returns the number of events that have occurred while the thresholds have not been reached. Prototype Inputs Outputs Returns INT4 spe2488SetThreshCntr(sSPE2488_HNDL deviceHandle, sSPE2488_MASK *pthreshCntr) deviceHandle pthreshold pthreshold : device Handle (from spe2488Add) : (pointer to) allocated memory : event counters Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE, SPE2488_INACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 121 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface 5.11 Alarm, Status and Statistics Functions Configuring the Device Statistics: spe2488CfgStats This function configures the behaviour of the device counts. Prototype Inputs Outputs Returns INT4 spe2488CfgStats(sSPE2488_HNDL deviceHandle, sSPE2488_CFG_CNT cfgCnt) deviceHandle cfgCnt : device Handle (from spe2488Add) : counters configuration block None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ACTIVE, SPE2488_INACTIVE Valid States Side Effects None Statistics Collection Routine: spe2488GetCnt This function retrieves all the device counts; it should be called by the application code, in the context of a separate periodic task. It is the user's responsibility to ensure that this function is called often enough to prevent the device counts from saturating. Prototype Inputs Outputs Returns INT4 spe2488GetCnt(sSPE2488_HNDL deviceHandle, sSPE2488_STAT_CNT *pcnt) deviceHandle pcnt pcnt : device Handle (from spe2488Add) : (pointer to) allocated memory : current device counts Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE When a port is not in use (and the device is in QUAD mode), indirect accesses to this port's registers will time out. These timeouts can substantially increase the execution time of this function. So, the USER should make use of spe2488GetCntStm4 whenever one of the 4 slices is not used, in order to selectively retrieve the per-slice device counts. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 122 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Statistics Collection Routine: spe2488GetCntStm4 This function retrieves the per-slot device counts; it should be called by the application code, in the context of a task. It is the USER's responsibility to ensure that this function is called often enough to prevent the device counts from saturating. Prototype Inputs INT4 spe2488GetCntStm4(sSPE2488_HNDL deviceHandle, UINT2 stm4, sSPE2488_STAT_CNT *pcnt) deviceHandle stm4 pcnt pcnt : device Handle (from spe2488Add) : STM-4 index : (pointer to) allocated memory : current device counts Outputs Returns Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE None Getting Counter for SOH and LOH Block: spe2488GetCntSOHLOH This function retrieves the specified device counts block. It is the user's responsibility to poll this function often enough to prevent the device counts from saturating. Prototype INT4 spe2488GetCntSOHLOH(sSPE2488_HNDL deviceHandle, UINT2 stm4, sSPE2488_STAT_CNT_SOH *pcntSOH, sSPE2488_STAT_CNT_LOH *pcntLOH) deviceHandle stm4 pcntSOH pcntLOH pcntSOH pcntLOH Inputs : device Handle (from spe2488Add) : STM-4 index : (pointer to) allocated memory : (pointer to) allocated memory : current device counts : current device counts Outputs Returns Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 123 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Getting Counter for RPOH Block: spe2488GetCntRPOH This function retrieves the specified device counts block. It is the user's responsibility to poll this function often enough to prevent the device counts from saturating. Prototype Inputs INT4 spe2488GetCntRPOH(sSPE2488_HNDL deviceHandle, UINT2 stm4, sSPE2488_STAT_CNT_RPOH *pcntRPOH) deviceHandle stm4 pcntRPOH pcntRPOH : device Handle (from spe2488Add) : STM-4 index : (pointer to) allocated memory : current device counts Outputs Returns Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE None Getting Counter for TPOH Block: spe2488GetCntTPOH This function retrieves the specified device counts block. It is the user's responsibility to poll this function often enough to prevent the device counts from saturating. Prototype Inputs INT4 spe2488GetCntTPOH(sSPE2488_HNDL deviceHandle, UINT2 stm4, sSPE2488_STAT_CNT_TPOH *pcntTPOH) deviceHandle stm4 pcntTPOH pcntTPOH : device Handle (from spe2488Add) : STM-4 index : (pointer to) allocated memory : current device counts Outputs Returns Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 124 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Getting Current Alarm Status: spe2488GetStatus This function retrieves the current alarm status by reading all the alarm status registers. It is the user's responsibility to ensure that the passed structure points to an area of memory large enough to hold a copy of the counter structure. Prototype Inputs Outputs Returns INT4 spe2488GetStatus(sSPE2488_HNDL deviceHandle, sSPE2488_STATUS *palm) deviceHandle palm palm : device Handle (from spe2488Add) : (pointer to) allocated memory : current alarm status Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE When a port is not in use (and the device is in QUAD mode), indirect accesses to this port's registers will time out. These timeouts can substantially increase the execution time of this function. So, the USER should make use of spe2488GetStatusStm4 whenever one of the 4 slices is not used, in order to selectively retrieve the per-slice device status. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 125 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Getting Current Alarm Status: spe2488GetStatusStm4 This function retrieves a per-port snapshot of the current status form the status registers of the SPECTRA-2488. It is the USER's responsibility to ensure that the passed structure points to an area of memory large enough to hold a copy of the status structure. Prototype Inputs INT4 spe2488GetStatusStm4(sSPE2488_HNDL deviceHandle, UINT2 stm4, sSPE2488_STATUS *palm) deviceHandle stm4 palm palm : device Handle (from spe2488Add) : STM-4 index : (pointer to) allocated memory : current alarm status Outputs Returns Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE None Getting Current Alarm Status for IO block: spe2488GetStatusIO This function returns the current status of the IO block. Prototype Inputs Outputs Returns INT4 spe2488GetStatusIO(sSPE2488_HNDL deviceHandle, sSPE2488_STATUS_IO *palmIO) deviceHandle palmIO palmIO : device Handle (from spe2488Add) : (pointer to) allocated memory : current alarm status Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 126 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Getting Current Alarm Status for SOH and LOH block: spe2488GetStatusSOHLOH This function returns the current status of the SOH and LOH blocks for a given STM-4 slice. Prototype INT4 spe2488GetStatusSOHLOH(sSPE2488_HNDL deviceHandle, UINT2 stm4, sSPE2488_STATUS_SOH *palmSOH, sSPE2488_STATUS_LOH *palmLOH) deviceHandle stm4 palmSOH palmLOH palmSOH palmLOH Inputs : device Handle (from spe2488Add) : STM-4 index : (pointer to) allocated memory : (pointer to) allocated memory : current alarm status : current alarm status Outputs Returns Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE None Getting Current Alarm Status for RPOH block: spe2488GetStatusRPOH This function returns the current status of the RPOH block for a given STM-4 slice. Prototype INT4 spe2488GetStatusRPOH(sSPE2488_HNDL deviceHandle, UINT2 stm4, sSPE2488_STATUS_RPOH *palmRPOH) deviceHandle stm4 palmRPOH palmRPOH Inputs : device Handle (from spe2488Add) : STM-4 index : (pointer to) allocated memory : current alarm status Outputs Returns Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 127 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Getting Current Alarm Status for TPOH block: spe2488GetStatusTPOH This function returns the current status of the TPOH block for a given STM-4 slice. Prototype INT4 spe2488GetStatusTPOH(sSPE2488_HNDL deviceHandle, UINT2 stm4, sSPE2488_STATUS_TPOH *palmTPOH) deviceHandle stm4 palmTPOH palmTPOH Inputs : device Handle (from spe2488Add) : STM-4 index : (pointer to) allocated memory : current alarm status Outputs Returns Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE None 5.12 Device Diagnostics Testing Register Accesses: spe2488DiagTestReg This function verifies the hardware access to the device registers by writing and reading back values. Prototype Inputs Outputs Returns INT4 spe2488DiagTestReg(sSPE2488_HNDL deviceHandle) deviceHandle : device Handle (from spe2488Add) None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_FAILURE Valid States Side Effects SPE2488_PRESENT None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 128 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Enabling Line-Side Line Loopbacks: spe2488DiagLineSideLineLoop This function Clears/Sets a Line-Side Line Loopback. It is up to the user to perform any tests on the looped data. Prototype Inputs INT4 spe2488DiagLineSideLineLoop(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 enable) deviceHandle stm4 enable : device Handle (from spe2488Add) : STM-4 index : sets loop if non-zero, else clears loop Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE Will inhibit the flow of active data Enabling Line-Side System Loopbacks: spe2488DiagLineSideSysLoop This function Clears/Sets a Line-Side System Loopback. It is up to the user to perform any tests on the looped data. Prototype Inputs INT4 spe2488DiagLineSideSysLoop(sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 enable) deviceHandle stm4 enable : device Handle (from spe2488Add) : STM-4 index : sets loop if non-zero, else clears loop Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE Will inhibit the flow of active data Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 129 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Enabling System-Side Line Loopbacks: spe2488DiagSysSideLineLoop This function Clears/Sets a System-Side Line Loopback. It is up to the user to perform any tests on the looped data. Prototype Inputs INT4 spe2488DiagSysSideLineLoop (sSPE2488_HNDL deviceHandle, UINT2 stm4, UINT2 au3, UINT2 enable) deviceHandle stm4 au3 enable : device Handle (from spe2488Add) : STM-4 index : AU-3 index : sets loop if non-zero, else clears loop Outputs Returns None Success = SPE2488_SUCCESS Failure = SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_INVALID_ARG Valid States Side Effects SPE2488_ACTIVE Will inhibit the flow of active data 5.13 Callback Functions The SPECTRA-2488 driver has the capability to callback to functions within the user code when certain events occur. These events and their associated callback routine declarations are detailed below. There is no user code action that is required by the driver for these callbacks; this means that the user is free to implement these callbacks in any manner or else to delete them from the driver. The names given to the callback functions are given as examples only. The addresses of the callback functions invoked by the spe2488DPR function are passed during the spe2488Init call (inside a DIV). However, the user shall use the exact same prototype. The Application is left responsible for releasing the passed DPV as soon as possible (to avoid running out of DPV buffers) by calling sysSpe2488DPVBufferRtn either within the callback function or later inside the Application code. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 130 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Notifying the Application of IO Events: cbackSpe2488IO This callback function is provided by the user and is used by the DPR to report significant IO section events back to the application. This function should be non-blocking. Typically, the callback routine sends a message to another task with the event identifier and other context information. The task that receives this message can then process this information according to the system requirements. NOTE: the callback function's addresses are passed to the driver doing the spe2488Init call. If the address of the callback function was passed as a NULL at initialization, no callback will be made. Prototype Inputs Outputs Returns Valid States Side Effects void cbackSpe2488IO(sSPE2488_USR_CTXT usrCtxt, sSPE2488_DPV *pdpv) usrCtxt pdpv : user context (from spe2488Add) : (pointer to) DPV that describes this event None None SPE2488_ACTIVE None Notifying the Application of SOH Events: cbackSpe2488SOH This callback function is provided by the user and is used by the DPR to report significant SOH section events back to the application. This function should be non-blocking. Typically, the callback routine sends a message to another task with the event identifier and other context information. The task that receives this message can then process this information according to the system requirements. NOTE: the callback function's addresses are passed to the driver doing the spe2488Init call. If the address of the callback function was passed as a NULL at initialization, no callback will be made. Prototype Inputs Outputs Returns Valid States Side Effects void cbackSpe2488SOH(sSPE2488_USR_CTXT usrCtxt, sSPE2488_DPV *pdpv) usrCtxt pdpv : user context (from spe2488Add) : (pointer to) DPV that describes this event None None SPE2488_ACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 131 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Notifying the Application of LOH Events: cbackSpe2488LOH This callback function is provided by the user and is used by the DPR to report significant LOH section events back to the application. This function should be non-blocking. Typically, the callback routine sends a message to another task with the event identifier and other context information. The task that receives this message can then process this information according to the system requirements. NOTE: the callback function's addresses are passed to the driver doing the spe2488Init call. If the address of the callback function was passed as a NULL at initialization, no callback will be made. Prototype Inputs Outputs Returns Valid States Side Effects void cbackSpe2488LOH(sSPE2488_USR_CTXT usrCtxt, sSPE2488_DPV *pdpv) usrCtxt pdpv : user context (from spe2488Add) : (pointer to) DPV that describes this event None None SPE2488_ACTIVE None Notifying the Application of RPOH Events: cbackSpe2488RPOH This callback function is provided by the user and is used by the DPR to report significant RPOH section events back to the application. This function should be non-blocking. Typically, the callback routine sends a message to another task with the event identifier and other context information. The task that receives this message can then process this information according to the system requirements. NOTE: the callback function's addresses are passed to the driver doing the spe2488Init call. If the address of the callback function was passed as a NULL at initialization, no callback will be made. Prototype Inputs Outputs Returns Valid States Side Effects void cbackSpe2488RPOH(sSPE2488_USR_CTXT usrCtxt, sSPE2488_DPV *pdpv) usrCtxt pdpv : user context (from spe2488Add) : (pointer to) DPV that describes this event None None SPE2488_ACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 132 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Notifying the Application of RPOH-TU3 Events: cbackSpe2488RPOHTU3 This callback function is provided by the user and is used by the DPR to report significant RPOH-TU3 section events back to the application. This function should be non-blocking. Typically, the callback routine sends a message to another task with the event identifier and other context information. The task that receives this message can then process this information according to the system requirements. NOTE: the callback function's addresses are passed to the driver doing the spe2488Init call. If the address of the callback function was passed as a NULL at initialization, no callback will be made. Prototype Inputs Outputs Returns Valid States Side Effects void cbackSpe2488RPOHTU3(sSPE2488_USR_CTXT usrCtxt, sSPE2488_DPV *pdpv) usrCtxt pdpv : user context (from spe2488Add) : (pointer to) DPV that describes this event None None SPE2488_ACTIVE None Notifying the Application of TPOH Events: cbackSpe2488TPOH This callback function is provided by the user and is used by the DPR to report significant TPOH section events back to the application. This function should be non-blocking. Typically, the callback routine sends a message to another task with the event identifier and other context information. The task that receives this message can then process this information according to the system requirements. NOTE: the callback function's addresses are passed to the driver doing the spe2488Init call. If the address of the callback function was passed as a NULL at initialization, no callback will be made. Prototype Inputs Outputs Returns Valid States Side Effects void cbackSpe2488TPOH(sSPE2488_USR_CTXT usrCtxt, sSPE2488_DPV *pdpv) usrCtxt pdpv : user context (from spe2488Add) : (pointer to) DPV that describes this event None None SPE2488_ACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 133 SPECTRA-2488 (PM5315) Driver Manual Application Programming Interface Notifying the Application of DPGM Events: cbackSpe2488DPGM This callback function is provided by the user and is used by the DPR to report significant DPGM section events back to the application. This function should be non-blocking. Typically, the callback routine sends a message to another task with the event identifier and other context information. The task that receives this message can then process this information according to the system requirements. NOTE: the callback function's addresses are passed to the driver doing the spe2488Init call. If the address of the callback function was passed as a NULL at initialization, no callback will be made. Prototype Inputs Outputs Returns Valid States Side Effects void cbackSpe2488DPGM(sSPE2488_USR_CTXT usrCtxt, sSPE2488_DPV *pdpv) usrCtxt pdpv : user context (from spe2488Add) : (pointer to) DPV that describes this event None None SPE2488_ACTIVE None Notifying the Application of APGM Events: cbackSpe2488APGM This callback function is provided by the user and is used by the DPR to report significant APGM section events back to the application. This function should be non-blocking. Typically, the callback routine sends a message to another task with the event identifier and other context information. The task that receives this message can then process this information according to the system requirements. NOTE: the callback function's addresses are passed to the driver doing the spe2488Init call. If the address of the callback function was passed as a NULL at initialization, no callback will be made. Prototype Inputs Outputs Returns Valid States Side Effects void cbackSpe2488APGM(sSPE2488_USR_CTXT usrCtxt, sSPE2488_DPV *pdpv) usrCtxt pdpv : user context (from spe2488Add) : (pointer to) DPV that describes this event None None SPE2488_ACTIVE None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 134 SPECTRA-2488 (PM5315) Driver Manual Hardware Interface 6 HARDWARE INTERFACE The SPECTRA-2488 driver interfaces directly with the user's hardware. In this section, a listing of each point of interface is shown, along with a declaration and any specific porting instructions. It is the responsibility of the user to connect these requirements into the hardware, either by defining a macro or by writing a function for each item listed. Care should be taken when matching parameters and return values. 6.1 Device I/O Reading from a Device Register: sysSpe2488Read The most basic hardware connection, sysSpe2488Read, reads the contents of a specific register location. This Macro should be defined by the user to reflect the target system's addressing logic. There is no need for error recovery in this function. Format Prototype Inputs #define sysSpe2488Read(base, offset) UINT2 sysSpe2488Read(void *base, UINT2 offset) base offset : base address of device being accessed : offset to the memory location as it appears in the hardware data-sheet. Outputs Returns None value read from the addressed register location Writing to a Device Register: sysSpe2488Write The most basic hardware connection, sysSpe2488Write, writes the supplied value to the specific register location. This macro should be defined by the user to reflect the target system's addressing logic. There is no need for error recovery in this function. Format Prototype Inputs #define sysSpe2488Write(base, offset, data) UINT2 sysSpe2488Write(void *base, UINT2 offset, UINT2 data) base offset data : base address of device being accessed : offset to the memory location as it appears in the hardware data-sheet. : data to be written Outputs None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 135 SPECTRA-2488 (PM5315) Driver Manual Hardware Interface Returns Value written to the addressed register location Polling a Bit: sysSpe2488PollBit This function simply polls a register masked data until it is zero or times out. Format Prototype Inputs #define sysSpe2488PollBit(base, offset, mask) UINT2 sysSpe2488PollBit(void *base, UINT2 offset, UINT2 mask) base offset mask : base address of device being accessed : offset to the memory location as it appears in the hardware data-sheet. : mask to apply to byte read Outputs Returns None Success = 0 Failure = 6.2 System-Specific Interrupt Servicing The porting of an ISR routine between platforms is a rather difficult task. There are many different implementations of these hardware level routines. In this driver, the user is responsible for installing an interrupt handler (sysSpe2488ISRHandler) in the interrupt vector table of the system processor. This handler shall call spe2488ISR for each device that has interrupt servicing enabled, to perform the ISR related housekeeping required by each device. During execution of the API function spe2488ModuleStart / spe2488ModuleStop the driver informs the application that it is time to install / uninstall this shell via sysSpe2488ISRHandlerInstall / sysSpe2488ISRHandlerRemove, that needs to be supplied by the user. Note: A device can be initialized with ISR disabled. In that mode, the user should periodically invoke a provided `polling' routine (spe2488Poll) that in turn calls spe2488ISR. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 136 SPECTRA-2488 (PM5315) Driver Manual Hardware Interface Installing the ISR Handler: sysSpe2488ISRHandlerInstall This function installs the user-supplied Interrupt-Service Routine (ISR), sysSpe2488ISRHandler, into the processor's interrupt vector table. Informs the application that it is time to install the user-supplied function sysSpe2488DPRTask into the RTOS as a task. Format Prototype Inputs Outputs Returns #define sysSpe2488ISRHandlerInstall() INT4 sysSpe2488ISRHandlerInstall(void) None None Success = 0 Failure = ISR Handler: sysSpe2488ISRHandler This routine is invoked when one or more SPECTRA-2488 devices raise the interrupt line to the microprocessor. This routine invokes the driver-provided routine, spe2488ISR, for each device registered with the driver. Format Prototype Inputs Outputs Returns #define sysSpe2488ISRHandler() void sysSpe2488ISRHandler(void) None None None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 137 SPECTRA-2488 (PM5315) Driver Manual Hardware Interface DPR Task: sysSpe2488DPRTask This routine is installed as a separate task within the RTOS. It runs periodically and retrieves the interrupt status information sent to it by spe2488ISR and then invokes spe2488DPR for the appropriate device. Format Prototype Inputs Outputs Returns #define sysSpe2488DPRTask() void sysSpe2488DPRTask(void) None None None Removing the ISR Handler: sysSpe2488ISRHandlerRemove This function disables interrupt processing for this device. Informs the application that it is time to remove (suspend) the user supplied task, sysSpe2488DPRTask. Removes the user-supplied Interrupt-Service Routine (ISR), sysSpe2488ISRHandler, from the processor's interrupt vector table. Format Prototype Inputs Outputs Returns #define sysSpe2488ISRHandlerRemove() void sysSpe2488ISRHandlerRemove(void) None None None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 138 SPECTRA-2488 (PM5315) Driver Manual RTOS Interface 7 RTOS INTERFACE The SPECTRA-2488 driver requires the use of some RTOS resources. In this section, a listing of each required resource is shown, along with a declaration and any specific porting instructions. It is the responsibility of the user to connect these requirements into the RTOS, either by defining a macro or writing a function for each item listed. Care should be taken when matching parameters and return values. 7.1 Memory Allocation/De-Allocation Allocating Memory: sysSpe2488MemAlloc This function allocates specified number of bytes of memory. Format Prototype Inputs Outputs Returns #define sysSpe2488MemAlloc(numBytes) UINT1 *sysSpe2488MemAlloc(UINT4 numBytes) numBytes : number of bytes to be allocated None Success = Pointer to first byte of allocated memory Failure = NULL pointer (memory allocation failed) Freeing Memory: sysSpe2488MemFree This function frees memory allocated using sysSpe2488MemAlloc. Format Prototype Inputs Outputs Returns #define sysSpe2488MemFree(pfirstByte) void sysSpe2488MemFree(UINT1 *pfirstByte) pfirstByte : pointer to first byte of the memory region being de-allocated None None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 139 SPECTRA-2488 (PM5315) Driver Manual RTOS Interface Initializing Memory: sysSpe2488MemSet This function initializes a block of memory with a given value. Format Prototype Inputs #define sysSpe2488MemSet(pmem, val, sz) UINT1 *sysSpe2488MemSet(UINT1 *pmem, UINT1 val, UINT4 sz) pmem val sz : (pointer to) first byte of the memory region to to initialize : value to use : size of the block to initialize : updated memory block Outputs Returns pmem None Copying Memory: sysSpe2488MemCpy This function copy a block of memory. Format Prototype Inputs #define sysSpe2488MemCpy(pdst, psrc, sz) UINT1 *sysSpe2488MemCpy(UINT1 *pdst, UINT1 *psrc, UINT2 sz) pdst psrc sz pdst : (pointer to) first byte of destination block : (pointer to) first byte of source block : size of the block to initialize : updated memory block Outputs Returns None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 140 SPECTRA-2488 (PM5315) Driver Manual RTOS Interface 7.2 Buffer Management All operating systems provide some sort of buffer system, particularly for use in sending and receiving messages. The following calls, provided by the user, allow the driver to Get and Return buffers from the RTOS. It is the user's responsibility to create any special resources or pools to handle buffers of these sizes during the sysSpe2488BufferStart call. Starting Buffer Management: sysSpe2488BufferStart This function alerts the RTOS that the time has come to make sure that the ISV buffers and DPV buffers are available and sized correctly. This may involve the creation of new buffer pools and it may involve nothing, depending on the RTOS. Format Prototype Inputs Outputs Returns #define sysSpe2488BufferStart() INT4 sysSpe2488BufferStart(void) None None Success = 0 Failure = Getting an ISV Buffer: sysSpe2488ISVBufferGet This function gets a buffer from the RTOS that will be used by the ISR code to create an Interrupt-Service Vector (ISV) . The ISV consists of data transferred from the devices interrupt status registers. Format Prototype Inputs Outputs Returns #define sysSpe2488ISVBufferGet() sSPE2488_ISV *sysSpe2488ISVBufferGet(void) None None Success = (pointer to) a ISV buffer Failure = NULL (pointer) Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 141 SPECTRA-2488 (PM5315) Driver Manual RTOS Interface Returning an ISV Buffer: sysSpe2488ISVBufferRtn This function returns an ISV buffer to the RTOS when the information in the block is no longer needed by the DPR. Format Prototype Inputs Outputs Returns #define sysSpe2488ISVBufferRtn(pisv) void sysSpe2488ISVBufferRtn(sSPE2488_ISV *pisv) pisv : (pointer to) a ISV buffer None None Getting a DPV Buffer: sysSpe2488DPVBufferGet This function gets a buffer from the RTOS that will be used by the DPR code to create a Deferred-Processing Vector (DPV) . The DPV consists of information about the state of the device that is to be passed to the user via a callback function. Format Prototype Inputs Outputs Returns #define sysSpe2488DPVBufferGet() sSPE2488_DPV *sysSpe2488DPVBufferGet(void) None None Success = (pointer to) a DPV buffer Failure = NULL (pointer) Returning a DPV Buffer: sysSpe2488DPVBufferRtn This function returns a DPV buffer to the RTOS when the information in the block is no longer needed by the DPR. Format Prototype Inputs Outputs Returns #define sysSpe2488DPVBufferRtn(pdpv) void sysSpe2488DPVBufferRtn(sSPE2488_DPV *pdpv) pdpv : (pointer to) a DPV buffer None None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 142 SPECTRA-2488 (PM5315) Driver Manual RTOS Interface Stopping Buffer Management: sysSpe2488BufferStop This function alerts the RTOS that the driver no longer needs any of the ISV buffers or DPV buffers, and that if any special resources were created to handle these buffers, they can be deleted now. Format Prototype Inputs Outputs Returns #define sysSpe2488BufferStop() void sysSpe2488BufferStop(void) None None None 7.3 Timers Sleeping a Task: sysSpe2488TimerSleep This function suspends execution of a driver task for a specified number of milliseconds. Format Prototype Inputs Outputs Returns #define sysSpe2488TimerSleep(msec) void sysSpe2488TimerSleep(UINT4 msec) msec : sleep time in milliseconds None Success = 0 Failure = Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 143 SPECTRA-2488 (PM5315) Driver Manual RTOS Interface 7.4 Preemption Disabling Preemption: sysSpe2488PreemptDisable This routine prevents the calling task from being preempted. If the driver is in interrupt mode, this routine locks out all interrupts, as well as other tasks in the system. If the driver is in polling mode, this routine locks out other tasks only. Format Prototype Inputs Outputs Returns #define sysSpe2488PreemptDisable() INT4 sysSpe2488PreemptDisable(void) None None Preemption key (passed back as an argument in sysSpe2488PreemptEnable) Re-Enabling Preemption: sysSpe2488PreemptEnable This routine allows the calling task to be preempted. If the driver is in interrupt mode, this routine unlocks all interrupts and other tasks in the system. If the driver is in polling mode, this routine unlocks other tasks only. Format Prototype Inputs Outputs Returns #define sysSpe2488PreemptEnable(key) void sysSpe2488PreemptEnable(INT4 key) key : preemption key (returned by sysSpe2488PreemptDisable) None None Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 144 SPECTRA-2488 (PM5315) Driver Manual Porting the SPECTRA-2488 Driver 8 PORTING THE SPECTRA-2488 DRIVER This section outlines how to port the SPECTRA-2488 device driver to your hardware and RTOS platform. However, this manual can offer only guidelines for porting the SPECTRA-2488 driver as each platform and application is unique. 8.1 Driver Source Files The C source files listed in the following table contain the code for the SPECTRA-2488 driver. You may need to modify the code or develop additional code. The code is in the form of constants, macros, and functions. For the ease of porting, the code is grouped into source files (src) and header files (inc). The source files contain the functions and the header files contain the structures, constants and macros. Directory src File spe2488_api1.c Description All the API functions that take care of module, device and profile management All the SPECTRA-2488 specific API functions. Hardware interface functions Internal functions for interrupt servicing Internal functions for profiles RTOS interface functions Internal functions for statistics All the remaining internal functions All API headers Driver macros, constants and definitions (such as register mapping and bit masks) SPECTRA-2488 error codes Prototype of non-API functions HW interface macros and prototype RTOS interface macros and prototypes spe2488_api2.c spe2488_hw.c spe2488_isr.c spe2488_prof.c spe2488_rtos.c spe2488_stat.c spe2488_util.c inc spe2488_api.h spe2488_defs.h spe2488_err.h spe2488_fns.h spe2488_hw.h spe2488_rtos.h Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 145 SPECTRA-2488 (PM5315) Driver Manual Porting the SPECTRA-2488 Driver Directory File spe2488_strs.h spe2488_typs.h Description driver structures types definitions Example callback functions and example code Prototype and definitions for the example code Example debug code for reporting register accesses to the device Prototype and definitions for the debug code example spe2488_app.c spe2488_app.h spe2488_debug.c spe2488_debug.h 8.2 Driver Porting Procedures The following procedures summarize how to port the SPECTRA-2488 driver to your platform. The subsequent sections describe these procedures in more detail. To port the SPECTRA-2488 driver to your platform: Step 1: Port the driver's RTOS extensions (page 146): Step 2: Port the driver to your hardware platform (page 148): Step 3: Port the driver's application-specific elements (page 149): Step 4: Build the driver (page 150). Step 1: Porting the RTOS Extensions The RTOS extensions encapsulate all RTOS specific services and data types used by the driver. These RTOS extensions include: * * * Memory Management Task management Message queues, semaphores and timers The compiler-specific data type definitions are located in spe2488_typs.h. The files spe2488_rtos.h and spe2488_rtos.c contain macros and functions for RTOS specific services. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 146 SPECTRA-2488 (PM5315) Driver Manual Porting the SPECTRA-2488 Driver To port the driver's RTOS extensions: 1. Modify the data types in spe2488_typs.h. The number after the type identifies the data-type size. For example, UINT4 defines a 4-byte (32-bit) unsigned integer. Substitute the compiler types that yield the desired types as defined in this file. 2. Modify the RTOS specific macros in spe2488_rtos.h: Service Type Memory Macro Name sysSpe2488MemAlloc sysSpe2488MemFree sysSpe2488MemCpy Description Allocates a memory block Frees a memory block Copies the contents of one memory block to another Fills a memory block with a specified value sysSpe2488MemSet 3. Modify the RTOS specific functions in spe2488_rtos.c: Service Type Timer Pre-emption Lock/Unlock Function Name sysSpe2488TimerSleep Description Delays the task execution for a given number of milliseconds Disables pre-emption of the currently executing task by any other task or interrupt Re-enables pre-emption of a task by other tasks and/or interrupts Starts buffer management Stops buffer management Gets an ISV buffer from the ISV buffer queue Returns an ISV buffer to the ISV buffer queue Gets a DPV buffer from the DPV buffer queue Returns a DPV buffer to the DPV buffer queue sysSpe2488PreemptDisabl e sysSpe2488PreemptEnable sysSpe2488BufferStart sysSpe2488BufferStop sysSpe2488ISVBufferGet Buffer sysSpe2488ISVBufferRtn sysSpe2488DPVBufferGet sysSpe2488DPVBufferRtn Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 147 SPECTRA-2488 (PM5315) Driver Manual Porting the SPECTRA-2488 Driver Step 2: Porting the Driver to Your Hardware Platform This section describes how to modify the SPECTRA-2488 driver for your hardware platform. To port the driver to your hardware platform: 1. Modify the hardware specific macros in spe2488_hw.h: Service Type Register Access Function Name sysSpe2488Read Description Reads a device register given its real address in memory Writes to a device register given its real address in memory sysSpe2488Write 2. Modify the hardware specific functions in spe2488_hw.c: Service Type Register Access Interrupt Function Name sysSpe2488PollBit Description Polls a device register given its real address in memory the interrupt vector table and spawn the DPR task sysSpe2488ISRHandlerInstall Installs the interrupt handler in sysSpe2488ISRHandlerRemove Removes the interrupt handler from the vector table and suspend the DPR task Interrupt handler for the SPECTRA-2488 device Task that calls the SPECTRA2488 DPR sysSpe2488ISRHandler sysSpe2488DPRTask Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 148 SPECTRA-2488 (PM5315) Driver Manual Porting the SPECTRA-2488 Driver Step 3: Porting the Application-Specific Elements Porting the application-specific elements includes coding the application callback and defining all the constants used by the API. To port the driver's application-specific elements: 1. Modify the base value of SPE2488_ERR_BASE (default = -500) in spe2488_err.h. 2. Modify the application specific constants in spe2488_defs.h: Task Constant SPE2488_MAX_DEVS Description The maximum number of SPECTRA-2488 devices that can be supported by the driver The maximum number of initialization profiles that can be added to the driver Default 5 SPE2488_MAX_INIT_PROFS 100 3. Define the following application specific constants for your RTOS-specific services in spe2488_rtos.h: Task Constant SPE2488_MAX_ISV_BUF Description The queue message depth of the queue used for passing interrupt context between the ISR handler and the DPR task The queue message depth of the queue used for pass interrupt context between the DPR task and the callback functions Default 50 SPE2488_MAX_DPV_BUF 950 4. Define the following constants for your OS-specific services in spe2488_hw.h: Task Constant SPE2488_DPR_TASK_PRIORITY SPE2488_DPR_TASK_STACK_SZ SPE2488_MAX_DELAY Description Deferred Task (DPR) task priority DPR task stack size, in bytes Delay between two consecutive polls of a busy bit Default 85 8192 100us Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 149 SPECTRA-2488 (PM5315) Driver Manual Porting the SPECTRA-2488 Driver Task Constant SPE2488_MAX_POLL Description Maximum number of times a busy bit will be polled before the operation times out The maximum number of messages in the message queue. Default 100 SPE2488_MAX_MSGS 1000 4. Code the callback functions according to your application. There are sample callback functions in spe2488_app.c. You can use these callback functions or you can customize them before using the driver. The driver will call these callback functions when an event occurs on the device. These functions must conform to the following prototype (cback should be replaced with your callback function name): void cback(sSPE2488_USR_CTXT usrCtxt, sSPE2488_DPV *pdpv) Step 4: Building the Driver This section describes how to build the SPECTRA-2488 driver. To build the driver: 1. Modify the Makefile to reflect the absolute path of your code, your compiler and compiler options. 2. Choose from among the different compile options supported by the driver as per your requirements. 3. Compile the source files and build the SPECTRA-2488 API driver library using your make utility. 4. Link the SPECTRA-2488 API driver library to your application code. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 150 SPECTRA-2488 (PM5315) Driver Manual Porting the SPECTRA-2488 Driver APPENDIX A: DRIVER RETURN CODES Table 29 describes the driver's return codes. Table 29: Return Codes Return Type SPE2488_ERR_MEM_ALLOC SPE2488_ERR_INVALID_ARG SPE2488_ERR_INVALID_MODULE_STATE SPE2488_ERR_INVALID_MIV SPE2488_ERR_PROFILES_FULL SPE2488_ERR_INVALID_PROFILE SPE2488_ERR_INVALID_PROFILE_NUM SPE2488_ERR_INVALID_DEVICE_STATE SPE2488_ERR_DEVS_FULL SPE2488_ERR_DEV_ALREADY_ADDED SPE2488_ERR_INVALID_DEV SPE2488_ERR_INVALID_DIV SPE2488_ERR_INT_INSTALL SPE2488_ERR_INVALID_MODE SPE2488_ERR_INVALID_REG SPE2488_ERR_POLL_TIMEOUT Description Memory allocation failure Invalid argument Invalid module state Invalid Module Initialization Vector (MIV) Maximum number of profiles already added Invalid profile Invalid profile number Invalid device state Maximum number of devices already added Device already added Invalid device handle Invalid Device Initialization Vector (DIV) Error while installing interrupts Invalid ISR/polling mode Invalid register number Time-out while polling Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 151 SPECTRA-2488 (PM5315) Driver Manual Porting the SPECTRA-2488 Driver APPENDIX B: SPECTRA-2488 EVENTS This section of the manual describes the events used in the SPECTRA-2488 device driver. Table 30: SPECTRA-2488 Events for IO callbacks Event Name SPE2488_EVENT_IO_APARRER Description Add parity error Table 31: SPECTRA-2488 Events for SOH callbacks Event Name SPE2488_EVENT_SOH_BIPE SPE2488_EVENT_SOH_LOS SPE2488_EVENT_SOH_LOF SPE2488_EVENT_SOH_OOF SPE2488_EVENT_SOH_TIU SPE2488_EVENT_SOH_TIM Description Section BIP error Loss of signal Loss of frame Out of frame Trace identifier unstable Trace identifier mismatch Table 32: SPECTRA-2488 Events for LOH callbacks Event Name SPE2488_EVENT_LOH_SF SPE2488_EVENT_LOH_SD SPE2488_EVENT_LOH_REI SPE2488_EVENT_LOH_BIPE SPE2488_EVENT_LOH_COSSM SPE2488_EVENT_LOH_COAPS SPE2488_EVENT_LOH_APSBF SPE2488_EVENT_LOH_RDI Description Signal failure Signal degrade Line remote error indication Line BIP error Change of SSM message Change of APS bytes APS byte failure Line remote defect indication Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 152 SPECTRA-2488 (PM5315) Driver Manual Porting the SPECTRA-2488 Driver Event Name SPE2488_EVENT_LOH_AIS Description Line alarm indication signal Table 33: SPECTRA-2488 Events for RPOH, RPOH-TU3 and TPOH callbacks Event Name SPE2488_EVENT_POH_TIU SPE2488_EVENT_POH_TIM SPE2488_EVENT_POH_PJE SPE2488_EVENT_POH_NJE SPE2488_EVENT_POH_PREI SPE2488_EVENT_POH_BIPE SPE2488_EVENT_POH_COPERDI SPE2488_EVENT_POH_PERDI SPE2488_EVENT_POH_PRDI SPE2488_EVENT_POH_PPDI SPE2488_EVENT_POH_UNEQ SPE2488_EVENT_POH_PSLM SPE2488_EVENT_POH_PSLU SPE2488_EVENT_POH_COPSL SPE2488_EVENT_POH_PPJ SPE2488_EVENT_POH_NPJ SPE2488_EVENT_POH_FOVR SPE2488_EVENT_POH_FUDR SPE2488_EVENT_POH_LOP SPE2488_EVENT_POH_AIS Description Path trace identifier unstable Path trace identifier mismatch Positive justification event Negative justification event Path remote error indication Path BIP error Change of path enhanced remote defect indication Path enhanced remote defect indication Path remote defect indication Path payload defect indication Path unequipped Path signal label mismatch Path signal label unstable Change of path signal label Positive pointer justification Negative pointer justification FIFO overflow FIFO underflow Loss of pointer alarm indication signal Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 153 SPECTRA-2488 (PM5315) Driver Manual Porting the SPECTRA-2488 Driver Event Name SPE2488_EVENT_POH_PAISC SPE2488_EVENT_POH_PLOPC SPE2488_EVENT_POH_PAIS SPE2488_EVENT_POH_PLOP Description Path alarm indication signal concatenated Path alarm indication signal concatenated Path alarm indication signal Path loss of pointer Table 34: SPECTRA-2488 Events for DPGM and APGM callbacks Event Name SPE2488_EVENT_PGM_MON_ERR SPE2488_EVENT_PGM_MON_E1B1 SPE2488_EVENT_PGM_MON_SYNC Description Monitor byte error Monitor change of B1/E1 Monitor change of synchronization state Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 154 SPECTRA-2488 (PM5315) Driver Manual Porting the SPECTRA-2488 Driver APPENDIX C: CODING CONVENTIONS This section describes the coding conventions used in the implementation of all PMC driver software. Variable Type Definitions Table 35: Variable Type Definitions Type UINT1 UINT2 UINT4 INT1 INT2 INT4 Description unsigned integer - 1 byte unsigned integer - 2 bytes unsigned integer - 4 bytes signed integer - 1 byte signed integer - 2 bytes signed integer - 4 bytes Naming Conventions Table 36 presents a summary of the naming conventions followed by all PMC driver software. A detailed description is then given in the following sub-sections. The names used in the drivers are verbose enough to make their purpose fairly clear. This makes the code more readable. Generally, the device's name or abbreviation appears in the prefix. Table 36: Naming Conventions Type Macros Constants Structures Case Uppercase Uppercase Hungarian Notation Naming convention prefix with "m" and device abbreviation prefix with device abbreviation prefix with "s" and device abbreviation Examples mSPE2488_WRITE SPE2488_MAX_DEVS sSPE2488_DDB Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 155 SPECTRA-2488 (PM5315) Driver Manual Porting the SPECTRA-2488 Driver Type API Functions Porting Functions Other Functions Variables Case Hungarian Notation Hungarian Notation Hungarian Notation Hungarian Notation Naming convention prefix with device name Examples spe2488Add() prefix with "sys" and device sysSpe2488Read() name myOwnFunction() maxDevs Pointers to Hungarian variables Notation Global variables Hungarian Notation prefix variable name with "p" pmaxDevs prefix with device name spe2488Mdb Macros * * * * Macro names must be all uppercase. Words shall be separated by an underscore. The letter `m' in lowercase is used as a prefix to specify that it is a macro, then the device abbreviation must appear. Example: mSPE2488_WRITE is a valid name for a macro. Constants * * * * Constant names must be all uppercase. Words shall be separated by an underscore. The device abbreviation must appear as a prefix. Example: SPE2488_REG is a valid name for a constant. Structures * * * * Structure names must be all uppercase. Words shall be separated by an underscore. The letter `s' in lowercase must be used as a prefix to specify that it is a structure, then the device abbreviation must appear. Example: sSPE2488_DDB is a valid name for a structure. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 156 SPECTRA-2488 (PM5315) Driver Manual Porting the SPECTRA-2488 Driver Functions API Functions * * * Naming of the API functions must follow the hungarian notation. The device's full name in all lowercase shall be used as a prefix. Example: spe2488Add() is a valid name for an API function. Porting Functions Porting functions correspond to all functions that are HW and/or RTOS dependent. * * * * Naming of the porting functions must follow the hungarian notation. The `sys' prefix shall be used to indicate a porting function. The device's name starting with an uppercase must follow the prefix. Example: sysSpe2488Read() is a hardware / RTOS specific. Other Functions * * Other Functions are all the remaining functions that are part of the driver and have no special naming convention. However, they must follow the hungarian notation. Example: myOwnFunction() is a valid name for such a function. Variables * * Naming of variables must follow the hungarian notation. A pointer to a variable shall use `p' as a prefix followed by the variable name unchanged. If the variable name already starts with a `p', the first letter of the variable name may be capitalized, but this is not a requirement. Double pointers might be prefixed with `pp', but this is not required. Global variables must be identified with the device's name in all lowercase as a prefix. Examples: maxDevs is a valid name for a variable, pmaxDevs is a valid name for a pointer to maxDevs, and spe2488Mdb is a valid name for a global variable. Note that both pprevBuf and pPrevBuf are accepted names for a pointer to the prevBuf variable, and that both pmatrix and ppmatrix are accepted names for a double pointer to the variable matrix. * * Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 157 SPECTRA-2488 (PM5315) Driver Manual Porting the SPECTRA-2488 Driver File Organization Table 37 presents a summary of the file naming conventions. All file names must start with the device abbreviation, followed by an underscore and the actual file name. File names should convey their purpose with a minimum amount of characters. If a file size is getting too big one might separate it into two or more files, providing that a number is added at the end of the file name (e.g. spe2488_api1.c or spe2488_api2.c). There are 4 different types of files: * * * * The API file containing all the API functions The hardware file containing the hardware dependent functions The RTOS file containing the RTOS dependent functions The other files containing all the remaining functions of the driver Table 37: File Naming Conventions File Type API Hardware Dependent RTOS Dependent Other File Name spe2488_api1.c, spe2488_api.h spe2488_hw.c, spe2488_hw.h spe2488_rtos.c, spe2488_rtos.h spe2488_init.c, spe2488_init.h API Files * * The name of the API files must start with the device abbreviation followed by an underscore and `api'. If needed, a number can be added at the end of the name. Examples: spe2488_api1.c is the only valid name for the file that contains the first part of the API functions, spe2488_api.h is the only valid name for the file that contains all of the API functions headers. Hardware Dependent Files * * The name of the hardware dependent files must start with the device abbreviation followed by an underscore and `hw'. If needed, a number might be added at the end of the file name. Examples: spe2488_hw.c is the only valid name for the file that contains all of the hardware dependent functions, and spe2488_hw.h is the only valid name for the file that contains all of the hardware dependent functions headers. Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 158 SPECTRA-2488 (PM5315) Driver Manual Porting the SPECTRA-2488 Driver RTOS Dependent Files * * The name of the RTOS dependent files must start with the device abbreviation followed by an underscore and `rtos'. If needed, a number might be added at the end of the file name. Examples: spe2488_rtos.c is the only valid name for the file that contains all of the RTOS dependent functions, and spe2488_rtos.h is the only valid name for the file that contains all of the RTOS dependent functions headers. Other Driver Files * The names of the remaining driver files must start with the device abbreviation followed by an underscore and the file name itself, which should convey the purpose of the functions within that file with a minimum amount of characters. Examples: spe2488_init.c is a valid name for a file that would deal with initialization of the device, and spe2488_init.h is a valid name for the corresponding header file. * Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 159 SPECTRA-2488 (PM5315) Driver Manual LIST OF TERMS APPLICATION: Refers to protocol software used in a real system as well as validation software written to validate the SPECTRA-2488 driver on a validation platform. API (Application Programming Interface): Describes the connection between this module and the user's Application code. ISR (Interrupt-Service Routine): A common function for intercepting and servicing device events. This function is kept as short as possible because an Interrupt preempts every other function starting the moment it occurs and gives the service function the highest priority while running. Data is collected, Interrupt indicators are cleared and the function ended. DPR (Deferred-Processing Routine): This function is installed as a task, at a user configurable priority, that serves as the next logical step in Interrupt processing. Data that was collected by the ISR is analyzed and then calls are made into the Application that inform it of the events that caused the ISR in the first place. Because this function is operating at the task level, the user can decide on its importance in the system, relative to other functions. DEVICE : One SPECTRA-2488 Integrated Circuit. There can be many devices, all served by this one driver module * DIV (Device Initialization Vector): Structure passed from the API to the device during initialization; it contains parameters that identify the specific modes and arrangements of the physical device being initialized. DDB (Device Data Block): Structure that holds the Configuration Data for each device. * MODULE: All of the code that is part of this driver, there is only one instance of this module connected to one or more SPECTRA-2488 chips. * MIV (Module Initialization Vector): Structure passed from the API to the module during initialization, it contains parameters that identify the specific characteristics of the driver module being initialized. MDB (Module Data Block): Structure that holds the Configuration Data for this module. RTOS (Real-Time Operating System): The host for this driver * * Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 160 SPECTRA-2488 (PM5315) Driver Manual ACRONYMS APGM: Add bus PRBS Generator and Monitor API: Application Programming Interface DDB: Device Data Block DIV: Device Initialization Vector DPGM: Drop bus PRBS Generator and Monitor DPR: Deferred-Processing Routine DPV: Deferred-Processing (routine) Vector FIFO: First In, First Out IO: Input / Output ISR: Interrupt-Service Routine ISV: Interrupt-Service (routine) Vector LOH: Line overhead MDB: Module Data Block MIV: Module Initialization Vector POH: Path Overhead RPOH: Receive Path Overhead RTOS: Real-Time Operating System SOH: Section Overhead TPOH: Transmit Path Overhead Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 161 SPECTRA-2488 (PM5315) Driver Manual INDEX A Alarm monitoring, 19 Alarm, status and statistics, 23, 25 APGM, 58, 114 API, 22, 61, 160 Application programming interface...see API, 22 return codes...see Error, 151 source files, 145 E Error errDevice, 57, 60, 65 errModule, 38, 56, 60, 61 return codes, 151 Events Input / Output, 152 Line Overhead, 152 Path Overhead, 153 PRBS generator and monitor, 154 Section Overhead, 152 C Callback functions ADD bus PRBS Generator and Monitor, 39, 58, 134 DROP bus PRBS Generator and Monitor, 39, 57, 134 Input / Output, 39, 57, 131 Line Overhead, 39, 57, 132 Receive Path Overhead, 39, 57, 132 Receive Path Overhead TU3, 39, 57, 133 Section Overhead, 39, 57, 131 Transmit Path Overhead, 39, 57, 133 H Hardware interface, 22 I Input / Output, 18, 23, 25 Interrupt architecture, 31 mask, 44 mode, 57 service routine...see ISR, 23 service vector...see ISV, 59 servicing, 17 IO...see Input / Output, 72 ISR, 23, 24, 31, 117, 160, 161 mask, 44, 117 mode configuration, 117 spe2488DPR, 32 spe2488ISR, 31, 119 spe2488Poll, 33, 119 ISV, 59, 119, 120, 141, 161 D DDB, 23, 24, 56, 160, 161 Deferred processing routine...see DPR, 23 Device activate / de-activate, 17, 68 add / delete, 16, 65 data block, 56 data block...see DDB, 23 diagnostics, 19, 23, 25, 128 initialization, 16, 66 initialization vector...see DIV, 38 management, 30, 65 read / write registers, 17, 69 update, 19, 67 DIV, 38, 56, 63, 64, 66, 160, 161 DPGM, 58, 112 DPR, 23, 24, 31, 120, 160, 161 DPV, 60, 120, 130, 141, 142, 161 Driver example files, 146 header files, 145 porting procedures...see Porting, 146 L Line overhead, 18, 23, 25 LOH...see Line overhead, 83 M MDB, 23, 24, 55, 60, 160, 161 MIV, 38, 61, 160, 161 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 162 SPECTRA-2488 (PM5315) Driver Manual Module data block...see MDB, 23 initialization vector...see MIV, 38 management, 29, 61 open / close, 16, 61 start / stop, 16, 62 interface, 22, 139 memory, 139 porting...see Porting, 146 preemption, 144 standard types, 155 timers, 143 P Path overhead, 19, 23, 25 POH...see Path Overhead, 92 Polling, 17, 31, 33 Porting Application Interface, 149 Building the Driver, 150 Hardware Interface, 148 RTOS interface, 146 Profile initialization, 38, 61, 64 management, 63 S Section overhead, 18, 23, 25 Software states...see State, 26 SOH...see Section overhead, 77 State Device, 27 Module, 27 stateDevice, 37, 57, 60 stateModule, 37, 56, 60 Statistics, 19 Statistics collection, 17 T Termination line overhead, 83 path overhead, 93 path overhead TU3, 94 section overhead, 77 TPOH...see Path Overhead, 100 R Real-time operating system...see RTOS, 22 Return codes...see Error, 151 RPOH...see Path Overhead, 96 RPOH-TU3...see Path Overhead, 96 RTOS buffer management, 141 Proprietary and Confidential to PMC-Sierra, Inc., and for its Customers' Internal Use Document ID: PMC-2001285, Issue 2 163 |
Price & Availability of 2001285
 |
|
|
|
|
All Rights Reserved © IC-ON-LINE 2003 - 2022 |
| [Add Bookmark] [Contact Us] [Link exchange] [Privacy policy] |
|
Mirror Sites : [www.datasheet.hk]
[www.maxim4u.com] [www.ic-on-line.cn]
[www.ic-on-line.com] [www.ic-on-line.net]
[www.alldatasheet.com.cn]
[www.gdcy.com]
[www.gdcy.net] |